多值模型数据查询 mquery

请求路径和方法

注意

• 多值模型数据和原来写入的单值模型数据不兼容。单值模型数据需要通过原有的 /api/put 进口进行写入。同时多值写入数据需要通过 /api/mquery 接口进行查询，单值写入的数据需要通过 /api/query 进行查询。

请求内容

时间戳单位判断

时间戳的单位可以是秒或者毫秒。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 格式

说明

1. 一个查询中能够包含的总的Field个数最多不超过200个。 示例说明如下：

   假设现有一个查询包含3个子查询，第一个子查询包含3个Field, 第二个子查询包括2个Field, 第三个子查询包含6个Field，那么这个查询包含的总的Field个数totalFields = 3 + 2 + 6 = 11, 即查询时需要保证totalFields不能大于200。

2. tags 和 filters 都指定的场景下，后指定的过滤条件生效

域查询信息 JSON 格式

说明：关于 limit、dpValue、downsample、tags 和 filters 的详细信息请见下面的相关说明。

查询示例

请求： 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"
                }
            ]
        }
    ]
}

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

Limit：子查询返回数据点的最大数目。默认值是 0，代表不限制返回点数量。Offset：子查询返回数据点的偏移量。默认值也是 0，代表不偏移返回的数据点。

注意：limit 和 offset 不能为负数。同时，limit 和 offset 是对最后多值返回结果的分页查询处理，而不是对某一域查询结果进行处理。

示例

返回第 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） 说明

根据用户设置的数值限制条件，过滤最终的返回数据点。支持 “>”, “<”, “=”, “<=”, “>=”, “!=”。注意 不同 fields 之间的 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"
                }
            ]
        }
    ]
}

降采样 (Downsample) 说明

当查询的时间范围比较长，只需返回一定精度的数据时使用。查询格式如下：

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

其中：

• interval：指数值，如 5、60 等，特殊的“0all”表示时间维度聚合为一个点。
• units：s 代表秒，m 代表分，h 代表小时，d 代表天，n 代表月，y 代表年。说明：支持基于日历时间间隔的降采样。要使用日历界限，您需要在时间单位 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

注意：在域查询信息中，downsample 不是必要条款。您甚至可以在查询时明确标明其值为 null 或者空（””），例如：{“downsample”: null} 或者 {“downsample”: “”}，这样就不会触发数据点降采样。但是，如果又一个域查询使用了 downsample，在同一子查询下的所有域查询信息都需要包括 downsample 并且采用同样的降采样区间。

聚合（Aggregate）说明

在降采样后会得到多条时间线的值，并且这些时间线的时间戳是对齐的，而聚合就是把多条时间线的值按各个对齐时刻聚合为一条时间线的结果（注意：如果只有一条时间线，则不进行聚合）。聚合时必须要求每条时间线在对应时刻都有值，如果某条时间线在某个时刻没有值，则会进行插值，插值描述如下。注意：在域查询信息中，aggregator 是必要条款，但是可以通过 none 来指明不做聚合运算。但是，TSDB多值模型不支持在同一个查询中有的域做聚合，有的域不做聚合。

插值

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

例如：降采样以及聚合条件为{“downsample”: “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 做 groupBy，相同的 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]
    ]
  }
]