---
title: "查询指定数据流"
date: 2026-03-26
lastmod: 2026-03-26
description: "介绍如何在 Easysearch 中查询指定数据流的详细信息。"
tags: ["数据流", "索引管理", "查询"]
summary: "此 API 用于获取 Easysearch 集群中一个或多个指定数据流（Data Stream）的详细信息。
API #  GET /_data_stream/{name} API 的作用 #  获取指定数据流的元数据信息，包括：
 数据流名称：数据流的唯一标识符 时间戳字段配置：数据流使用的时间戳字段名称 底层索引列表：构成数据流的所有后备索引 生成号：数据流的当前生成版本号 健康状态：数据流的整体健康状态（GREEN/YELLOW/RED） 关联的索引模板：数据流所使用的索引模板名称  与 查询所有数据流 不同，此 API 允许通过数据流名称精确查询。
API 的参数 #  路由参数 #     参数 类型 是否必需 描述     name string 可选 数据流的名称，支持以下格式：
- 单个名称：logs-nginx
- 多个名称（逗号分隔）：logs-nginx,logs-redis
- 通配符：logs-*
如果不提供此参数，返回所有数据流    查询字符串参数 #  此 API 没有额外的查询字符串参数。
请求示例 #  # 查询单个数据流 GET /_data_stream/logs-nginx # 查询多个数据流（逗号分隔） GET /_data_stream/logs-nginx,logs-redis,logs-apache # 使用通配符查询 GET /_data_stream/logs-* # 使用通配符查询所有数据流 GET /_data_stream/* 响应示例 #  成功响应 - 单个数据流 #  { "data_streams": [ { "name": "logs-nginx", "timestamp_field": { "name": "@timestamp" }, "indices": [ { "index_name": "."
---


此 API 用于获取 Easysearch 集群中一个或多个指定数据流（Data Stream）的详细信息。

## API

```
GET /_data_stream/{name}
```

## API 的作用

获取指定数据流的元数据信息，包括：

- **数据流名称**：数据流的唯一标识符
- **时间戳字段配置**：数据流使用的时间戳字段名称
- **底层索引列表**：构成数据流的所有后备索引
- **生成号**：数据流的当前生成版本号
- **健康状态**：数据流的整体健康状态（GREEN/YELLOW/RED）
- **关联的索引模板**：数据流所使用的索引模板名称

与 [查询所有数据流](./get-all-data-streams.md) 不同，此 API 允许通过数据流名称精确查询。

## API 的参数

### 路由参数

| 参数 | 类型 | 是否必需 | 描述 |
|------|------|----------|------|
| `name` | string | 可选 | 数据流的名称，支持以下格式：<br>- 单个名称：`logs-nginx`<br>- 多个名称（逗号分隔）：`logs-nginx,logs-redis`<br>- 通配符：`logs-*`<br>如果不提供此参数，返回所有数据流 |

### 查询字符串参数

此 API **没有**额外的查询字符串参数。

## 请求示例

```bash
# 查询单个数据流
GET /_data_stream/logs-nginx

# 查询多个数据流（逗号分隔）
GET /_data_stream/logs-nginx,logs-redis,logs-apache

# 使用通配符查询
GET /_data_stream/logs-*

# 使用通配符查询所有数据流
GET /_data_stream/*
```

## 响应示例

### 成功响应 - 单个数据流

```json
{
  "data_streams": [
    {
      "name": "logs-nginx",
      "timestamp_field": {
        "name": "@timestamp"
      },
      "indices": [
        {
          "index_name": ".ds-logs-nginx-000001",
          "index_uuid": "xYz123ABC"
        },
        {
          "index_name": ".ds-logs-nginx-000002",
          "index_uuid": "aBc456DEF"
        },
        {
          "index_name": ".ds-logs-nginx-000003",
          "index_uuid": "GhI789JKL"
        }
      ],
      "generation": 3,
      "status": "GREEN",
      "template": "logs-template-nginx"
    }
  ]
}
```

### 成功响应 - 多个数据流

```json
{
  "data_streams": [
    {
      "name": "logs-nginx",
      "timestamp_field": {
        "name": "@timestamp"
      },
      "indices": [
        {
          "index_name": ".ds-logs-nginx-000001",
          "index_uuid": "xYz123ABC"
        }
      ],
      "generation": 1,
      "status": "GREEN",
      "template": "logs-template-nginx"
    },
    {
      "name": "logs-redis",
      "timestamp_field": {
        "name": "@timestamp"
      },
      "indices": [
        {
          "index_name": ".ds-logs-redis-000001",
          "index_uuid": "MnO345PQR"
        }
      ],
      "generation": 1,
      "status": "YELLOW",
      "template": "logs-template-redis"
    }
  ]
}
```

### 响应字段说明

| 字段 | 类型 | 描述 |
|------|------|------|
| `data_streams` | array | 数据流列表 |
| `name` | string | 数据流名称 |
| `timestamp_field.name` | string | 时间戳字段名称（通常是 `@timestamp`） |
| `indices` | array | 构成数据流的后备索引列表 |
| `indices.index_name` | string | 后备索引名称，格式为 `.ds-{data_stream}-{generation}` |
| `indices.index_uuid` | string | 后备索引的唯一标识符 |
| `generation` | integer | 数据流的当前生成号，每次滚动会递增 |
| `status` | string | 健康状态：<br>- `GREEN`：所有分片都正常分配<br>- `YELLOW`：主分片已分配，但副本分片未全部分配<br>- `RED`：部分主分片未分配 |
| `template` | string | 数据流使用的索引模板名称 |

### 错误响应

当查询不存在的数据流时：

```json
{
  "error": {
    "root_cause": [
      {
        "type": "resource_not_found_exception",
        "reason": "data_stream [non-existent-stream] missing"
      }
    ],
    "type": "resource_not_found_exception",
    "reason": "data_stream [non-existent-stream] missing"
  },
  "status": 404
}
```

## 名称匹配规则

1. **精确匹配**：完全匹配数据流名称
2. **逗号分隔**：可以同时查询多个数据流，用逗号分隔
3. **通配符**：
   - `*` 匹配任意字符
   - `logs-*` 匹配以 "logs-" 开头的所有数据流
   - `*-prod` 匹配以 "-prod" 结尾的所有数据流

## 使用场景

1. **检查数据流配置**：在操作前查看数据流的详细配置信息
2. **健康检查**：检查特定数据流的健康状态
3. **问题排查**：查看数据流的底层索引和生成信息
4. **资源规划**：评估数据流占用的索引数量和状态

## 与相关 API 的区别

| API | 功能 |
|-----|------|
| `GET /_data_stream` | 查询所有数据流 |
| `GET /_data_stream/{name}` | 查询指定名称的数据流 |
| `GET /_data_stream/_stats` | 获取数据流的统计信息 |
| `DELETE /_data_stream/{name}` | 删除数据流 |

## 注意事项

1. 此 API 只支持 GET 方法
2. 数据流名称区分大小写
3. 通配符查询可以匹配零个或多个数据流
4. 如果指定的数据流不存在，返回 404 错误

## 相关文档

- [创建数据流](./create-data-stream.md)
- [查询所有数据流](./get-all-data-streams.md)
- [删除数据流](./delete-data-stream.md)
- [查询数据流统计信息](./get-data-stream-stats.md)