如何通过HTTP API查询时间线最新数据点_时间序列数据库 TSDB(TSDB)-阿里云帮助中心

请求路径和方法

请求路径	请求方法	描述
/api/query/last	POST	获得时间线最新写入的数据点

重要

此端口完全兼容 OpenTSDB 协议。

请求内容

请求内容JSON格式

名字	类型	是否必需	描述	默认值	举例
queries	Array	是	子查询数组	无	见子查询说明
timestamp	Long	否	unix 时间戳，单位为秒或者毫秒，指定该参数时表示查询到该时间戳为止最新的数据点，否则表示查询当前最新的数据点	无	1539763573
hint	Map	否	查询 Hint 化	无	见查询 Hint 化说明
limit	Map	否	多个最新点查询。	无	见查询 Limit 化说明

子查询JSON格式

子查询中可以指定“Metric查询”格式或 “TSUID查询”格式。前者是通过指定时间线metric, tags作为检索条件执行查询；后者则是直接指定时间线的唯一ID来执行查询。在子查询的列表中，两种格式可以共存。

Metric 查询

名称	类型	是否必需	描述	默认值	举例
metric	String	是	待查询最新数据点的 Metric	无	cpu.usage
tags	String	否	待查询最新数据点的 Tags	无	host_name=host1
hint	Map	Map	查询 Hint 化	无	见查询 Hint 化说明

重要

这里不支持通过filters指定维度过滤条件，必须使用tags字段指定维度过滤条件

TSUID 查询

名称	类型	是否必需	描述	默认值	举例
tsuid	String	是	待查询最新数据点的 TSUID	无	00005B00005C0000F000005D0000EE00005E0000EF

重要

时间线的 TSUID 可以通过 /api/search/lookup 接口查询。
在高可用版本中，tsuid字段仅仅是形式上兼容，但不再支持tsuid查询功能。同样，在高可用版本中，/api/search/lookup 也不再支持返回tsuid值

请求 JSON 示例

任务：

查询包含 metric 名字为“cpu.usage” 和 tag 名字为“host_name=host1”的时间线的最新写入数据点。

同时，查询包含 TSUID 为00005B00005C00002E00005D0000EE00005E0000EF和00005B00005C0000F000005D0000EE00005E0000EF两条时间线的最新写入数据点。

请求：POST/api/query/last

请求体：

{
    "queries" : [
        {
            "metric":"cpu.usage",
            "tags" : {
                "host_name": "host1"
            }
        },
        {
            "tsuids": [
                "00005B00005C00002E00005D0000EE00005E0000EF",
                "00005B00005C0000F000005D0000EE00005E0000EF"
            ]
        }
    ]
}

响应说明

查询成功的 HTTP 响应码为 200，返回符合条件的时间线最新数据点，内容为JSON 格式数据；如果没有时间线满足条件，则返还空集。JSON说明如下：

名称	描述
metric	指标名
timestamp	最新数据点的时间戳
value	指标值
tags	数据点对应的tag键值集合
tsuid	数据点对应的时间线ID

响应体：

[{
    "metric": "cpu.usage",
    "timestamp": 1556418300000,
    "value": 30.3,
    "tags": {
        "host_name": "host1"
    },
    "tsuid": "00005B00005C00001D",
}, {
    "metric": "cpu.usage",
    "timestamp": 1556418300000,
    "value": 25.6,
    "tags": {
        "host_name": "host2",
        "cluster": "cluster1"
        "zone": "zone1"
    },
    "tsuid": "00005B00005C00002E00005D0000EE00005E0000EFE",
}, {
    "metric": "cpu.usage",
    "timestamp": 1556418300000,
    "value": 43.1,
    "tags": {
        "host_name": "host3",
        "cluster": "cluster1"
        "zone": "zone1"
    },
    "tsuid": "00005B00005C0000F000005D0000EE00005E0000EF",
}]

查询 Hint 化说明

场景说明

该特性主要是提高查询速度。假设某一个 tags A 命中的时间线明显大于其他的 tags B 命中的时间线，则需要舍弃，避免捞取 tags A 的大量时间线之后，被 tagsB 小规模时间线交集后，结果集等于 tagsB。

格式说明

当前版本只支持 tagk 级别的查询索引限制（hint 下的 tagk 是固定写法）
其中，0 表示不使用对应 tagk 的索引，反之 1 表示使用对应 tagk 的索引

版本说明

从 v2.6.1 版本开始支持 hint 特性

查询示例

子查询级别

{
  "queries": [
    {
      "metric": "sys.cpu.nice",
      "tags": {
        "host": "web01"
      },
      "hint": {
        "tagk": {
          "dc": 1
        }
      }
    }
  ]
}

整体查询级别

{
  "queries": [
    {
      "metric": "sys.cpu.nice",
      "tags": {
        "host": "web01"
      }
    }
  ],
  "hint": {
    "tagk": {
      "dc": 1
    }
  }
}

异常情况

不可同时指定 0 和 1

{
  "start": 1346846400,
  "end": 1346846400,
  "queries": [
    {
      "aggregator": "none",
      "metric": "sys.cpu.nice",
      "tags": {
        "dc": "lga",
        "host": "web01"
      }
    }
  ],
  "hint": {
    "tagk": {
      "dc": 1,
      "host": 0
    }
  }
}

会返回如下报错信息：

{
    "error": {
        "code": 400,
        "message": "The value of hint should only be 0 or 1, and there should not be both 0 and 1",
        "details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
    }
}

不可指定除了 0 和 1 之外的值

{
  "start": 1346846400,
  "end": 1346846400,
  "queries": [
    {
      "aggregator": "none",
      "metric": "sys.cpu.nice",
      "tags": {
        "dc": "lga",
        "host": "web01"
      }
    }
  ],
  "hint": {
    "tagk": {
      "dc": 100
    }
  }
}

会返回如下报错信息：

{
    "error": {
        "code": 400,
        "message": "The value of hint can only be 0 or 1, and it is detected that '100' is passed in",
        "details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
    }
}

查询Limit说明

Limit: 通过指定Limit可以查询多个最新数据点。当请求中没有指定Limit时，每条时间序列只返回一个最新的数据点。

JSON格式说明

名称	类型	是否必需	描述	默认值	举例
size	Integer	是	每个时间线最新数据点的最大数量。	无	5
from	Long	是	查询范围开始时间。	无	1346846400

示例

写入数据：4个时间序列每个时间线2条数据。

[{"metric":"testmetric", "tags":{"testmetric1_tagk":"testmetric1_tagv1"},"timestamp":1514736040, "value":1}, 
{"metric":"testmetric", "tags":{"testmetric2_tagk":"testmetric2_tagv1"},"timestamp":1514736050, "value":2},
{"metric":"testmetric", "tags":{"testmetric1_tagk":"testmetric1_tagv1"},"timestamp":1514736060, "value":3}, 
{"metric":"testmetric", "tags":{"testmetric2_tagk":"testmetric2_tagv1"},"timestamp":1514736070, "value":4},
{"metric":"testmetric", "tags":{"testmetric1_tagk":"testmetric1_tagv2"},"timestamp":1514736080, "value":5}, 
{"metric":"testmetric", "tags":{"testmetric2_tagk":"testmetric2_tagv2"},"timestamp":1514736090, "value":6},
{"metric":"testmetric", "tags":{"testmetric1_tagk":"testmetric1_tagv2"},"timestamp":1514736100, "value":7}, 
{"metric":"testmetric", "tags":{"testmetric2_tagk":"testmetric2_tagv2"},"timestamp":1514736110, "value":8}]

查询设置size为3，从时间戳1514736040到1514736100间共有7条数据

{
    "timestamp": 1514736100,
    "limit": {
        "size": 2,
        "from": 1514736040
    },
    "queries": [
        {
            "metric": "testmetric"
        }
    ]
}

查询结果，时间范围内每个时间线最多2条数据

[
    {
        "metric": "testmetric",
        "timestamp": 1514736060000,
        "value": 3.0,
        "tags": {
            "testmetric1_tagk": "testmetric1_tagv1"
        },
        "tsuid": "0200000200000200****",
        "version": 0,
        "dps": {
            "1514736040000": 1.0,
            "1514736060000": 3.0
        }
    },
    {
        "metric": "testmetric",
        "timestamp": 1514736100000,
        "value": 7.0,
        "tags": {
            "testmetric1_tagk": "testmetric1_tagv2"
        },
        "tsuid": "0400000200000200****",
        "version": 0,
        "dps": {
            "1514736080000": 5.0,
            "1514736100000": 7.0
        }
    },
    {
        "metric": "testmetric",
        "timestamp": 1514736070000,
        "value": 4.0,
        "tags": {
            "testmetric2_tagk": "testmetric2_tagv1"
        },
        "tsuid": "0E00000200000300****",
        "version": 0,
        "dps": {
            "1514736050000": 2.0,
            "1514736070000": 4.0
        }
    },
    {
        "metric": "testmetric",
        "timestamp": 1514736090000,
        "value": 6.0,
        "tags": {
            "testmetric2_tagk": "testmetric2_tagv2"
        },
        "tsuid": "1000000200000300****",
        "version": 0,
        "dps": {
            "1514736090000": 6.0
        }
    }
]