本文中含有需要您注意的重要提示信息，忽略該信息可能對您的業務造成影響，請務必仔細閱讀。
阿里云Elasticsearch提供Aliyun-TimeStream時序增強插件，支持通過API接口完成TimeStream索引的增刪改查，以及數據寫入和查詢。本文介紹如何使用TimeStream API。
背景信息
TimeStream是阿里云Elasticsearch團隊自研，并結合Elastic社區時序類產品特性共建的時序引擎。阿里云Elasticsearch提供的TimeStream時序增強功能插件，優化了Elasticsearch在存儲指標數據方面的DSL（Domain-Specific Language）查詢復雜且慢以及存儲成本過高等問題。詳細信息請參見TimeStream時序增強引擎介紹。
前提條件
已創建阿里云Elasticsearch實例，且實例版本為7.10（內核版本為1.8.0及以上）或7.16及以上（內核版本為1.7.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}/_updateBody中傳入自定義模板內容
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（時間線數量）的說明如下：
計算方式
獲取索引中每個主shard的時間線數量。由于每個shard的時間線不重復，所以一個索引的時間線數量就是全部主shard時間線數量的總和。
返回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寫入的數據要符合時序數據模型，默認模型如下。
字段 | 描述 |
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配置等。 |