TimeStream API功能介绍 - 检索分析服务Elasticsearch版

阿里云Elasticsearch提供Aliyun-TimeStream时序增强插件，支持通过API接口完成TimeStream索引的增删改查，以及数据写入和查询。本文介绍如何使用TimeStream API。

背景信息

TimeStream是阿里云Elasticsearch团队自研，并结合Elastic社区时序类产品特性共建的时序引擎。阿里云Elasticsearch提供的TimeStream时序增强功能插件，优化了Elasticsearch在存储指标数据方面的DSL（Domain-Specific Language）查询复杂且慢以及存储成本过高等问题。详细信息请参见TimeStream时序增强引擎介绍。

前提条件

已创建阿里云Elasticsearch实例，且实例版本为通用商业版7.16及以上、内核版本为1.7.0及以上，或者实例版本为通用商业版7.10、内核版本为1.8.0及以上。具体操作请参见创建阿里云Elasticsearch实例。

创建TimeStream索引

请求语法

Body为空
```
PUT _time_stream/{name}
```

Body中传入自定义模板内容

PUT _time_stream/{name}
{
  --- index template ---
}

使用说明

创建TimeStream索引无需传入index_patterns，TimeStream使用{name}作为index名称，不支持模糊匹配。

请求中的Body可为空，也可传入自定义模板内容，Body格式请参见Elasticsearch的Index templates接口。

示例

请求示例

PUT _time_stream/test_stream
{
  "template": {
    "settings": {
      "index.number_of_shards": "10"
    }
  }
}

返回示例
```
{
  "acknowledged" : true
}
```

更新TimeStream索引配置

请求语法

Body为空
```
POST _time_stream/{name}/_update
```

Body中传入自定义模板内容

POST _time_stream/{name}/_update
{
  --- index template ---
}

使用说明

更新接口传递的Body内容跟创建接口一致，具体可见创建TimeStream索引的使用说明。

更新TimeStream索引配置后，该配置不会立即应用到索引上，需要进行一次rollover后，配置才生效。

示例

请求示例

POST _time_stream/test_stream/_update
{
  "template": {
    "settings": {
      "index.number_of_shards": "10"
    }
  }
}

返回示例
```
{
  "acknowledged" : true
}
```

删除TimeStream索引

请求语法

Delete _time_stream/{name}

使用说明

支持模糊匹配或按逗号分隔索引实现批量删除。

警告删除TimeStream索引后，对应的索引数据会直接清除，请谨慎操作。

示例

请求示例
```
DELETE _time_stream/test_stream
```
返回示例
```
{
  "acknowledged" : true
}
```

查看TimeStream索引列表

请求语法

查看全部索引列表
```
GET _time_stream
```
查看指定的索引列表
```
GET _time_stream/{name}
```

使用说明

查看TimeStream索引列表，支持模糊查询，以及按逗号分隔索引。

示例

请求示例
```
GET _time_stream
```

返回示例

{
  "time_streams" : {
    "test_stream" : {
      "name" : "test_stream",
      "datastream_name" : "test_stream",
      "template_name" : ".timestream_test_stream",
      "template" : {
        "index_patterns" : [
          "test_stream"
        ],
        "template" : {
          "settings" : {
            "index" : {
              "number_of_shards" : "10"
            }
          }
        },
        "composed_of" : [
          ".system.timestream.template"
        ],
        "data_stream" : {
          "hidden" : true
        }
      }
    }
  }
}

查看TimeStream指标信息

请求语法

查看全部索引的指标信息
```
GET _time_stream/_stats
```
查看指定索引的指标信息
```
GET _time_stream/{name}/_stats
```

使用说明

查看TimeStream指标接口，可以获取索引的time_stream_count（时间线数量）等指标。

关于time_stream_count（时间线数量）的说明如下：

计算方式
1. 获取索引中每个主shard的时间线数量。由于每个shard的时间线不重复，所以一个索引的时间线数量就是全部主shard时间线数量的总和。
2. 返回TimeStream索引列表中时间线数量最大的索引。
注意事项
由于shard上获取时间线数量是从内部的时间线ID（_tsid）字段的docvalue数据直接获取，查询代价过高，所以增加了缓存策略。只读索引获取一次后就不再获取，正常索引缓存默认失效时间是5分钟，通过设置索引配置index.time_series.stats.refresh_interval可修改缓存更新时间，最小为1分钟。

示例

请求示例
```
GET _time_stream/_stats
```

返回示例

{
  "_shards" : {
    "total" : 4,
    "successful" : 4,
    "failed" : 0
  },
  "time_stream_count" : 2,
  "indices_count" : 2,
  "total_store_size_bytes" : 1278822,
  "time_streams" : [
    {
      "time_stream" : "test_stream",
      "indices_count" : 1,
      "store_size_bytes" : 31235,
      "tsidCount" : 1
    },
    {
      "time_stream" : "prom_index",
      "indices_count" : 1,
      "store_size_bytes" : 1247587,
      "tsidCount" : 317
    }
  ]
}

写入数据

请求语法

TimeStream使用Elasticsearch原生写入接口写入数据，包括bulk和index。

重要写入只支持append数据，不支持index存在的数据，也不支持update和delete。

写入模型

TimeStream写入的数据要符合时序数据模型，默认模型如下。

字段	描述
labels	指标相关的属性，唯一标识个体的元数据，时间线ID可由labels生成。
metrics	指标数据集合，指标只能为long或者double类型。
@timestamp	指标记录对应的时间，默认是毫秒级的时间戳。

数据示例如下。

{
  "labels": {
    "namespce": "cn-hanzhou",
    "clusterId": "cn-xxx-xxxxxx",
    "nodeId": "node-xxx",
    "label": "test-cluster",
    "disk_type": "cloud_ssd",
    "cluster_type": "normal"
  },
  "metrics": {
    "cpu.idle": 10.0,
    "mem.free": 100.1,
    "disk_ioutil": 5.2
  },
  "@timestamp": 1624873606000
}

示例

请求示例

POST test_stream/_doc
{
  "labels": {
    "namespce": "cn-hanzhou",
    "clusterId": "cn-xxx-xxxxxx",
    "nodeId": "node-xxx",
    "label": "test-cluster",
    "disk_type": "cloud_ssd",
    "cluster_type": "normal"
  },
  "metrics": {
    "cpu.idle": 10,
    "mem.free": 100.1,
    "disk_ioutil": 5.2
  },
  "@timestamp": 1624873606000
}

返回示例

{
  "_index" : ".ds-test_stream-2021.09.03-000001",
  "_id" : "suF_qnsBGKH6s8C_OuFS",
  "_version" : 1,
  "result" : "created",
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "failed" : 0
  },
  "_seq_no" : 0,
  "_primary_term" : 1
}

修改模型字段

在创建TimeStream索引时，支持传入自定义的单个或多个维度和指标字段。TimeStream内部会为维度和指标字段配置dynaimc_mapping，维度字段会设置time_series_dimension，Elasticsearch内部会用维度字段生成时间线ID；指标字段默认只使用doc_value。同时，配置字段时，TimeStream索引支持使用*进行模糊匹配。修改默认维度和指标字段的示例如下：

传入单个字段

PUT _time_stream/{name}
{
  --- index template ---
  "time_stream": {
    "labels_fields": "@label.*",
    "metrics_fields": "@metrics.*"
  }
}

传入多个字段

PUT _time_stream/{name}
{
  --- index template ---
  "time_stream": {
    "labels_fields": ["label.*", "dim*"],
    "metrics_fields": ["@metrics.*", "metrics.*"]
  }
}

参数	说明
labels_fields	默认为label.*，可选。
metrics_fields	默认为metrics.*，可选。

查询数据

请求语法

TimeStream使用Elasticsearch原生查询接口查询数据，包括search和get。

示例

请求示例
```
GET test_stream/_search
```

返回示例

{
  "took" : 172,
  "timed_out" : false,
  "_shards" : {
    "total" : 10,
    "successful" : 10,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 1,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : ".ds-test_stream-2021.09.03-000001",
        "_id" : "suF_qnsBGKH6s8C_OuFS",
        "_score" : 1.0
      }
    ]
  }
}

DownSample使用说明

DownSample（降采样）是时序场景的常用功能，在创建TimeStream索引时，支持配置DownSample规则。配置了DownSample规则后，您只需正常读写数据，TimeStream索引就能在内部完成对原始写入数据的DownSample处理。同时，在查询数据时，TimeStream索引会根据aggregation中的interval参数来选择合适的DownSample数据进行查询。

DownSample规则只需配置interval，TimeStream索引会结合labels和metrics配置进行DownSample处理。metrics字段经过DownSample处理后变成aggregate_metric_double类型，并生成max、min、sum和count四种数据。

由于DownSample触发时机是在Rollover阶段，对历史不再写入的索引进行DownSample处理，因此每个原始索引都会根据DownSample规则生成DownSample索引。DownSample索引默认继承全部原始索引的settings，如果需要单独配置DownSample索引的settings，可以在DownSample规则中指定。例如，如果DownSample索引的容量更小，可减少shard数量；保存时间更长，可单独指定ILM policy。

DownSample规则的配置示例如下。

PUT _time_stream/{name}
{
  "time_stream": {
    "downsample": [
      {
        "interval": "1m",
        "settings": {
           "index.lifecycle.name": "my-rollup-ilm-policy_60m",
           "index.number_of_shards": "1"
        }
      },
      {
        "interval": "10m"
      }
    ]
  }
}

time_stream参数增加downsample参数，用来配置downsample列表。downsample中的参数说明如下。

参数	可选性	说明
interval	必选	配置downsample的时间间隔，downsample将按照该时间间隔Rollup数据。最多支持配置5个interval规则，不同规则需要保持倍数关系，例如1m、10m、60m。
settings	可选	配置downsample索引的setting信息，例如生命周期配置、shard配置等。