---
title: "创建数据流"
date: 2026-02-02
lastmod: 2026-02-02
description: "介绍如何在 Easysearch 中创建数据流（Data Stream），用于管理时间序列数据。"
tags: ["数据流", "索引管理", "时间序列"]
summary: "数据流（Data Stream）是 Easysearch 中专门用于管理时间序列数据（如日志、事件和指标）的机制。数据流内部由多个底层索引组成，支持自动滚动（rollover）和生命周期管理。
API #  PUT /_data_stream/{name} API 的作用 #  创建数据流用于存储时间序列数据。数据流的主要特点包括：
 自动滚动管理：当满足特定条件（如文档数量、大小或时间）时，自动创建新的后备索引 简化操作：无需直接管理多个索引，统一通过数据流进行读写 优化查询：自动按时间顺序组织数据，提高时间范围查询的性能 生命周期管理：支持根据时间策略自动管理数据保留  创建数据流后会自动初始化第一个底层索引，名称格式为 .ds-{name}-000001。
API 的参数 #  路由参数 #     参数 类型 是否必需 描述     name string 必需 数据流的名称，必须是有效的索引名称格式    查询字符串参数 #     参数 类型 是否必需 默认值 描述     master_node_timeout time 可选 30s 等待主节点响应的超时时间。如果在指定时间内主节点未响应，操作将失败   timeout time 可选 30s 等待操作完成确认的超时时间   pretty boolean 可选 - 格式化 JSON 输出   format string 可选 json 指定响应格式（如 json、yaml）    使用前准备 #  在创建数据流之前，必须先创建相应的索引模板，模板中需要包含 data_stream 配置对象。"
---


数据流（Data Stream）是 Easysearch 中专门用于管理时间序列数据（如日志、事件和指标）的机制。数据流内部由多个底层索引组成，支持自动滚动（rollover）和生命周期管理。

## API

```
PUT /_data_stream/{name}
```

## API 的作用

创建数据流用于存储时间序列数据。数据流的主要特点包括：

- **自动滚动管理**：当满足特定条件（如文档数量、大小或时间）时，自动创建新的后备索引
- **简化操作**：无需直接管理多个索引，统一通过数据流进行读写
- **优化查询**：自动按时间顺序组织数据，提高时间范围查询的性能
- **生命周期管理**：支持根据时间策略自动管理数据保留

创建数据流后会自动初始化第一个底层索引，名称格式为 `.ds-{name}-000001`。

## API 的参数

### 路由参数

| 参数 | 类型 | 是否必需 | 描述 |
|------|------|----------|------|
| `name` | string | 必需 | 数据流的名称，必须是有效的索引名称格式 |

### 查询字符串参数

| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `master_node_timeout` | time | 可选 | 30s | 等待主节点响应的超时时间。如果在指定时间内主节点未响应，操作将失败 |
| `timeout` | time | 可选 | 30s | 等待操作完成确认的超时时间 |
| `pretty` | boolean | 可选 | - | 格式化 JSON 输出 |
| `format` | string | 可选 | json | 指定响应格式（如 json、yaml） |

## 使用前准备

在创建数据流之前，必须先创建相应的**索引模板**，模板中需要包含 `data_stream` 配置对象。

### 索引模板示例

```json
PUT /_index_template/my-data-stream-template
{
  "index_patterns": ["my-data-stream*"],
  "data_stream": {},
  "template": {
    "settings": {
      "number_of_shards": 1,
      "number_of_replicas": 1
    },
    "mappings": {
      "properties": {
        "@timestamp": {
          "type": "date"
        },
        "message": {
          "type": "text"
        }
      }
    }
  }
}
```

**重要说明：**
- 数据流必须包含一个时间戳字段（默认是 `@timestamp`）
- 索引模板的 `index_patterns` 必须与数据流名称匹配

## 请求示例

```bash
# 创建数据流
PUT /_data_stream/my-data-stream

# 带超时参数的创建请求
PUT /_data_stream/logs-nginx?master_node_timeout=60s&timeout=50s
```

## 响应示例

### 成功响应

```json
{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "my-data-stream"
}
```

### 错误响应

当缺少名称参数时：

```json
{
  "error": {
    "root_cause": [
      {
        "type": "illegal_argument_exception",
        "reason": "name is missing"
      }
    ],
    "type": "illegal_argument_exception",
    "reason": "name is missing"
  },
  "status": 400
}
```

## 注意事项

1. **数据流名称必须与索引模板匹配**：创建数据流前需要确保有匹配的索引模板，否则会失败
2. **时间戳字段**：写入数据流的文档必须包含时间戳字段
3. **不支持请求体**：创建数据流 API 不使用请求体，所有配置通过索引模板定义
4. **底层索引命名**：创建后自动生成第一个后备索引，名称格式为 `.ds-{name}-000001`
5. **不可更新**：数据流创建后无法修改，只能删除后重新创建

## 相关文档

- [查询所有数据流](./get-all-data-streams.md)
- [查询指定数据流](./get-specific-data-stream.md)
- [删除数据流](./delete-data-stream.md)