快速入门：时间序列数据流基础知识

使用本快速入门指南设置时间序列数据流 (TSDS)、摄取少量文档并运行基础查询。这些高层级步骤有助于您了解 TSDS 的工作原理，从而确定它是否适合您的数据。

*时间序列*是指按规则时间间隔收集的数据点序列。例如，您可以随时间跟踪 CPU 使用率或股票价格。本快速入门使用简化的天气传感器读数来展示 TSDS 如何帮助您随时间分析指标数据。

先决条件

在 Kibana 中访问开发工具控制台 (Dev Tools Console)，或使用其他方式发送 Elasticsearch API 请求
集群和索引权限
- 集群权限：manage_index_templates
- 索引权限：create_doc 和 create_index
熟悉时间序列数据流概念和Elasticsearch 索引与搜索基础知识

您可以使用任何 Elasticsearch 部署来按照本指南进行操作。要查看所有部署选项，请参阅部署 > 选择部署类型。若要快速上手，可在 Docker 中本地运行集群。

创建并查询 TSDS

创建索引模板

要创建数据流，您需要一个作为其基础的索引模板。该模板定义了数据流的结构和设置。（对于本快速入门，您无需了解模板的详细信息。）

TSDS 使用*维度 (dimension)* 字段和*指标 (metric)* 字段。维度用于唯一标识时间序列，通常基于描述性属性（如 location）。指标是随时间变化的测量值。

使用 _index_template 请求创建一个模板，其中包含两个用于识别的维度字段和两个用于天气测量的指标字段

						PUT _index_template/quickstart-tsds-template  
					{
  "index_patterns": ["quickstart-*"],
  "data_stream": { },   # Indicates this is a data stream, not a regular index.
  "priority": 100, 
  "template": {
    "settings": {
      "index.mode": "time_series"   # The required index mode for TSDS.
    },
    "mappings": {
      "properties": {
        "sensor_id": {
          "type": "keyword",
          "time_series_dimension": true   # Defines a dimension field.
        },
        "location": {
          "type": "keyword",
          "time_series_dimension": true   # Another dimension field.
        },
        "temperature": {
          "type": "half_float",
          "time_series_metric": "gauge"   # A supported field type for metrics.
         },
        "humidity": {
          "type": "half_float",
          "time_series_metric": "gauge"   # A second measurement.
        },
        "@timestamp": {
          "type": "date"
        }
      }
    }
  }
}
		
	

指示这是一个数据流，而不是常规索引。
TSDS 所需的索引模式。
定义一个维度字段。
另一个维度字段。
一种受支持的指标字段类型。
第二个测量值。

此示例定义了一个 @timestamp 字段以作说明。在大多数情况下，您可以使用默认的 @timestamp 字段（其默认类型为 date），而无需在映射中定义时间戳。

您应该会收到 "acknowledged": true 的响应，确认模板已创建。

创建数据流并添加示例数据

在此步骤中，创建一个名为 quickstart-weather 的新数据流，该数据流基于第 1 步中定义的索引模板。您可以在单个 API 调用中创建数据流并添加文档。

使用 _bulk API 请求一次性添加多个文档。请确保将时间戳调整为当前时间的前几分钟内。

						PUT quickstart-weather/_bulk
					{ "create":{ } }
{ "@timestamp": "2025-09-08T21:25:00.000Z", "sensor_id": "STATION-0001", "location": "base", "temperature": 26.7, "humidity": 49.9 }
{ "create":{ } }
{ "@timestamp": "2025-09-08T21:26:00.000Z", "sensor_id": "STATION-0002", "location": "base", "temperature": 27.2, "humidity": 50.1 }
{ "create":{ } }
{ "@timestamp": "2025-09-08T21:35:00.000Z", "sensor_id": "STATION-0003", "location": "base", "temperature": 28.1, "humidity": 48.7 }
{ "create":{ } }
{ "@timestamp": "2025-09-08T21:27:00.000Z", "sensor_id": "STATION-0004", "location": "satellite", "temperature": 32.4, "humidity": 88.9 }
{ "create":{ } }
{ "@timestamp": "2025-09-08T21:36:00.000Z", "sensor_id": "STATION-0005", "location": "satellite", "temperature": 32.3, "humidity": 87.5 }
		
	

响应显示了五个示例天气数据文档。

		{
  "errors": false,
  "took": 0,
  "items": [
    {
      "create": {
        "_index": ".ds-quickstart-weather-2025.09.08-000001",
        "_id": "cFJZQJlNh-Xl8V_rAAABmSs3x-A",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 2,
          "failed": 0
        },
        "_seq_no": 0,
        "_primary_term": 1,
        "status": 201
      }
    },
    {
      "create": {
        "_index": ".ds-quickstart-weather-2025.09.08-000001",
        "_id": "c-wsTT0T4CtI3hOuAAABmSs4skA",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 2,
          "failed": 0
        },
        "_seq_no": 1,
        "_primary_term": 1,
        "status": 201
      }
    },
    {
      "create": {
        "_index": ".ds-quickstart-weather-2025.09.08-000001",
        "_id": "Hdee5vMpBvZymWvHAAABmStA76A",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 2,
          "failed": 0
        },
        "_seq_no": 2,
        "_primary_term": 1,
        "status": 201
      }
    },
    {
      "create": {
        "_index": ".ds-quickstart-weather-2025.09.08-000001",
        "_id": "e3Z2UirUQldsjLr2AAABmSs5nKA",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 2,
          "failed": 0
        },
        "_seq_no": 3,
        "_primary_term": 1,
        "status": 201
      }
    },
    {
      "create": {
        "_index": ".ds-quickstart-weather-2025.09.08-000001",
        "_id": "N3-RYtQAp6JEsLRNAAABmStB2gA",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 2,
          "failed": 0
        },
        "_seq_no": 4,
        "_primary_term": 1,
        "status": 201
      }
    }
  ]
}
		
	

提示

如果您收到有关时间戳值的错误，请检查错误响应以了解有效的时间戳范围。有关详细信息，请参阅添加数据的可接受时间范围。

运行查询

现在您的数据流中已有了一些文档，您可以使用 ES|QL _query 端点来查询数据。此聚合示例显示了每个位置按小时存储桶划分的每个传感器的平均温度最大值。

						POST _query
					{
  query: "TS quickstart-weather | STATS max(avg_over_time(temperature) BY location, TBUCKET(1h)"
}
		
	

		MAX(AVG_OVER_TIME(temperature))|   location   |      TBUCKET(1h)
-------------------------------+--------------+------------------------
27.333333333333332             |base          |2025-09-08T21:00:00.000Z
32.359375                      |satellite     |2025-09-08T21:00:00.000Z
		
	

提示

您也可以在 Kibana 的数据视图 (data view) 中尝试此聚合。

后续步骤

本快速入门介绍了时间序列数据流的基础知识。要了解更多信息，请浏览以下主题

如果您正在使用 OpenTelemetry (OTLP) 或 Prometheus 数据，请参阅

有关本快速入门所用 API 的更多信息，请查看 Elasticsearch API 参考文档