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

多值模型最新数据点查询（新建mlast）

请求路径和方法

请求路径	请求方法	描述
/api/query/mlast	POST	获得多值模型指标数据中fields 最新写入的数据点。

请求内容

名称	类型	是否必选	描述	默认值	举例
queries	Array	是	子查询数组。	无	见子查询说明
timestamp	Long	否	unix 时间戳，单位为秒或者毫秒，指定该参数时表示查询到该时间戳为止最新的数据点，否则表示查询当前最新的数据点 Tags。这个是和 queries 相同级别参数，详情见示例。	无	1539763573
tupleFormat	Boolean	否	将查询 fields 的最新数据点元组结构返回，详情见示例。	false	false
tupleOffset	Long	否	数据分页时返回的tuple的偏移量。仅在tupleFormat为true时有效。	0	5
tupleLimit	Long	否	数据分页时返回的tuple最大数量。仅在tupleFormat为true时有效。	0	100
hint	Map	否	查询 Hint 化。	无	见查询 Hint 化说明
limit	Map	否	多个最新点查询。	无	见查询 Limit 化说明

注意

/api/query/mlast 只能用于多值模型数据，单值模型数据的最新数据点，请使用 /api/query/last 接口。

子查询JSON格式

名称	类型	是否必选	描述	默认值	举例
metric	String	是	待查询最新数据点的 Metric。	无	wind
fields	List	是	需要查询最新数据点的域，“*”代表查询 metric 下所有域。	无	{speed, level, description}
tags	String	否	待查询最新数据点的 Tags。	无	sensor = IOTE_1988_0001

hint|Map |否|查询 Hint 化|无 |见查询 Hint 化说明

请求 JSON 示例

任务：查询 “cpu” 指标下，标签为 “host_name=host1” 的 “usage_system” 和 “usage_idle” 域最新写入数据点。请求：POST/api/query/mlast请求体：

    {
        "tupleFormat": true,
        "tupleOffset":5,
        "tupleLimit":100,
        "timestamp" : 1551851846,
        "queries": [
            {
                "metric": "cpu",
                "fields": ["usage_system", "usage_idle"],
                "tags": {
                    "host_name": "host1"
                }
            }
        ]
    }

响应说明

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

名称	描述
metric	指标名
columns	返回结果集中的列名称，包括时间戳和查询的域名称
tags	数据点对应的tag键值集合
values	查询指标域的值，值的顺序和 columns 的顺序对应

注意

如果将 tupleFormat 设置成 false，增返回结果格式跟单值模型一致。这种场景下的详细响应内容可以参考/api/query/last 接口的介绍。

返回结果JSON示例

[
  {
    "metric": "wind",
    "columns": [
      "timestamp",
      "level",
      "speed"
    ],
    "tags": {
      "city": "hangzhou",
      "country": "china",
      "province": "zhejiang",
      "sensor": "IOTE_8859_0001"
    },
    "values": [
      [1346846405000, 5.1, 45.1]
    ]
  }
]

查询Hint化说明

场景说明

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

格式说明

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

版本说明

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

查询示例

子查询级别

{
  "queries": [
    {
      "metric": "demo.mf",
      "tags": {
        "sensor": "IOTE_8859_0001",
        "city": "hangzhou",
        "province": "zhejiang",
        "country": "china"
      },
      "fields": [
        "speed"
      ],
      "hint": {
        "tagk": {
          "dc": 1
        }
      }
    }
  ]
}

整体查询级别

{
  "queries": [
    {
      "metric": "demo.mf",
      "tags": {
        "sensor": "IOTE_8859_0001",
        "city": "hangzhou",
        "province": "zhejiang",
        "country": "china"
      },
      "fields": [
        "speed"
      ]
    }
  ],
  "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

示例

返回从时间戳1551850000到1551851846之间满足查询条件的最新300个数据点

{
  "tupleFormat":true,
  "limit":{
    "size":300,
    "from":1551850000
  }，
  "timestamp":1551851846,
  "queries":[
    {
      "metric":"cpu",
      "fields":["usage_system","usage_idle"],
      "tags":{
        "host_name":"host1"
       }
    }
  ]
}

详细示例说明可参考单值时间线最新数据点查询Limit说明。