多值查询最新数据点

多值模型最新数据点查询(新建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说明。