时间序列数据库 TSDB：多值数据查询

多值模型数据查询 mquery

请求路径和方法

请求内容

时间戳说明

时间戳的单位可以是秒或者毫秒。TSDB会通过数值大小来判断时间戳的单位，规则如下：

• 时间戳区间为 [4284768，9999999999]：判断为秒，表示的日期时间区间为：[1970-02-20 00:59:28，2286-11-21 01:46:39] 。

• 时间戳区间为 [10000000000，9999999999999]：判断为毫秒，表示的日期时间区间为：[1970-04-27 01:46:40.000,，2286-11-21 01:46:39.999] 。

• 时间戳区间为 （-∞，4284768）和（9999999999999，+∞）：判断为非法时间戳区间。

  说明

  适用于写入数据 （/api/put & /api/mput）和查询数据（/api/query & /api/mquery）两个接口。

单时间点数据查询

TSDB支持单时间点数据查询。您可以将开始时间和结束时间设置为相同的数值。

例如："start":1356998400，"end":1356998400。

子查询 JSON 格式

域查询信息 JSON 格式

查询示例

请求：POST/api/mquery请求体

{
    "start" : 1346846400,
    "end" :   1346846411,
    "msResolution" : true,
    "queries" : [
        {
            "metric" : "wind",
            "fields" : [
                {
                    "field" : "speed",
                    "aggregator" : "sum",
                    "downsample" : "2s-last",
                      "alias" : "speed_sum"
                },
                {
                    "field" : "*",
                    "aggregator" : "sum",
                    "downsample" : "2s-count",
                    "where":"speed>10"
                }
            ]
        }
    ]
}

数据分页查询（Limit 和 Offset）说明

Limit：子查询每条时间序列返回数据点的最大数目。默认值是0，代表不限制返回点数量。

Offset：子查询每条时间序列返回数据点的偏移量。默认值也是0，代表不偏移返回的数据点。

示例

返回第1001到1500的数据点，则limit设为500，offset设为1000。

{
    "start" : 1346846400,
    "end"  :  1346846411,
    "msResolution" : true,
    "queries" : [
        {
            "metric" : "wind",
            "fields" : [
                {
                    "field" : "*",
                    "aggregator" : "sum",
                    "downsample" : "2s-count"
                }
            ],
            "filters" : [
                {
                    "filter" : "IOTE_8859_0005|IOTE_8859_0004",
                    "tagk" : "sensor",
                    "type" : "literal_or"
                }
            ],
            "limit" : 500,
            "offset" : 1000
        }
    ]
}

值过滤（dpValue） 说明

根据用户设置的数值限制条件，过滤最终的返回数据点。支持 “>”、“<”、 “=”、 “<=”、 “>=”、 “!=”。

示例

{
    "start" : 1346846400,
    "end" :   1346846411,
    "msResolution" : true,
    "queries" : [
        {
            "metric" : "wind",
            "fields" : [
                {
                    "field" : "level",
                    "aggregator" : "avg",
                    "downsample" : "2s-avg",
                    "dpValue" : ">=8.0"
                }
            ],
            "filters" : [
                {
                    "filter" : "IOTE_8859_0005|IOTE_8859_0004",
                    "tagk" : "sensor",
                    "type" : "literal_or"
                }
            ]
        }
    ]
}

    {
       "start":1346046400,
       "end":1347056500,
       "queries":[
          {
             "aggregator":"none",
             "downsample":"5s-avg",
             "delta":true,
             "deltaOptions":{
                 "counter":true,
                 "counterMax":100
             }
             "metric":"sys.cpu.0",
             "dpValue":">=50",
             "tags":{
                "host":"localhost",
                "appName":"hitsdb"
             }
          }
       ]
    }

降采样（Downsample）说明

当查询的时间范围比较长，只需要返回每个时间间隔的统计值时使用。查询结果返回的时间戳是按照查询指定的间隔对齐后的时间区间起始值。查询格式如下：

<interval><units>-<aggregator>[-fill policy]

其中：

• interval：指数值，如 5、60等，特殊的“0all”表示时间维度聚合为一个点。

• units：s代表秒，m代表分，h代表小时，d代表天，n代表月，y代表年。

  说明

  • 默认按照时间戳取模对齐，即“对齐时间戳=数据时间戳-（数据时间戳 % interval）”。

  • 支持基于日历时间间隔的降采样。要使用日历界限，您需要在时间单位units后添加一个c。例如，1dc代表从当日零点到次日零点之间的 24 小时。

• aggregator：降采样使用的算子及其说明如下表所示。

Fill policy

Fill policy即填值。降采样先把所有时间线按照指定精度切分，并把每个降采样区间内的数据做一次运算，降采样后如果某个精度区间没有值，fill policy可以指定在这个时间点填充具体的值。比如某条时间线降采样后的时间戳为：t+0，t+20，t+30，此时如果不指定fill policy，只有3个值，如果指定了fill policy为null，此时间线会有4个值，其中t+10时刻的值为null。Fill policy与具体填充值的对应如下表所示。

Fixed Fill Policy

使用方法：将固定的填充值写到 “#”之后。填充值支持正负数。格式如下：

<interval><units>-<aggregator>-fixed#<number>

示例：1h-sum-fixed#6， 1h-avg-fixed#-8

降采样示例

示例：1m-avg，1h-sum-zero，1h-sum-near

聚合（Aggregate）说明

在降采样后会得到多条时间线的值，并且这些时间线的时间戳是对齐的，而聚合就是把多条时间线的值按各个对齐时刻聚合为一条时间线的结果（注意：如果只有一条时间线，则不进行聚合）。聚合时必须要求每条时间线在对应时刻都有值，如果某条时间线在某个时刻没有值，则会进行插值，插值描述如下。

插值

如果某条时间线某个精度区间没有值且没有使用fill policy进行填值，而待聚合的其他时间线中有一条时间线在此精度区间有值，则会对本时间线的这个缺值精度区间进行插值。

例如：降采样以及聚合条件为{"downsample": "10s-avg", "aggregator": "10s-avg", "aggregator": "sum"} ，有两条时间线需要使用 sum聚合，按10s-avg做降采样后的这两条时间线有值的时间戳分别为：

line 1：t+0，t+10，t+20，t+30、line 2：t+0，t+20，t+30。

第二条时间线 line 2 缺 “t+10” 这个时刻的值，那么在聚合前会对line 2的“t+10”这个时间点进行插值。插值的方法与聚合的算子有关，详见下面的算子列表。

Filters 说明

有以下两种方法可以指定filter：

• 在指定 tagk 时指定filter：

  • tagk = *：对tagk下面的tagv做分组，相同的tagv做聚合。

  • tagk = tagv1|tagv2：分别对tagk下面的tagv1和tagv2数据做聚合。

• 使用JSON格式指定filter：

Filter 类型说明

查询示例

包含 filter 的查询示例

请求体：

{
    "start" : 1346846400,
    "end" :   1346846411,
    "msResolution" : true,
    "queries" : [
        {
            "metric" : "wind",
            "fields" : [
                {
                    "field" : "speed",
                    "aggregator" : "none",
                    "alias" : "column_speed"
                },
                {
                      "field" : "*",
                    "aggregator" : "none",
                    "alias" : "column_"
                }
            ],
            "filters" : [
                {
                    "filter" : "IOTE_8859_0005|IOTE_8859_0004",
                    "tagk" : "sensor",
                    "type" : "literal_or"
                }
            ]
        }
    ]
}

查询结果说明

查询成功的HTTP响应码为200，响应内容为JSON格式数据。说明如下：

响应结果示例：

• Aggregator : None场景示例

[
   {
      "metric":"wind",
      "columns":[
         "timestamp",
         "column_speed",
         "column_description",
         "column_direction",
         "column_level",
         "column_speed"
      ],
      "tags":{
         "city":"hangzhou",
         "country":"china",
         "province":"zhejiang",
         "sensor":"IOTE_8859_0005"
      },
      "aggregatedTags":[],
      "values":[
         [ 1346846406000, null, "Fresh breeze", "East", 0.5, null ],
         [ 1346846407000, null, "Fresh breeze", "South", 1.5, null ]
   },
   {
      "metric":"wind",
      "columns":[
         "timestamp",
         "column_speed",
         "column_description",
         "column_direction",
         "column_level",
         "column_speed"
      ],
      "tags":{
         "city":"hangzhou",
         "country":"china",
         "province":"zhejiang",
         "sensor":"IOTE_8859_0004"
      },
      "aggregatedTags":[],
      "values":[
         [ 1346846400000, 40.4, "Fresh breeze", "East", 0.4, 40.4 ],
         [ 1346846401000, 41.4, "Fresh breeze", "South", 1.4, 41.4 ],
         [ 1346846402000, 42.4, "Fresh breeze", "West", 2.4, 42.4 ],
         [ 1346846403000, 43.4, "Fresh breeze", "North", 3.4,43.4 ]
   }
]

• Aggregator：Avg 的场景示例（查看杭州市所有sensor监控的平均风速和平均风等级）

[
  {
    "metric": "wind",
    "columns": [
      "timestamp",
      "avg_level",
      "avg_speed"
    ],
    "tags": {
      "city": "hangzhou"
    },
    "aggregatedTags": [
      "country",
      "province",
      "sensor"
    ],
    "values": [
      [1346846400000, 0.25, 40.25],
      [1346846401000, 1.25, 41.25],
      [1346846402000, 2.5, 42.5],
      [1346846411000, 5.5, null]
    ]
  }
]

查询 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=[])"
    }
}