Lindorm时序引擎提供了基于HTTP的应用程序编程接口API,本文介绍通过HTTP API方式查询多值数据。

接口API和方法

接口API 请求方法 描述
/api/mquery POST 查询多值数据。
注意 多值模型数据和之前写的单值模型数据不兼容。
  • 通过/api/put接口写入单值数据。
  • 通过/api/query接口查询单值数据。

请求参数

请求参数中包括子查询数组参数。

名称 类型 是否必选 示例值 描述
start Long 1499158925 开始时间。单位为秒或毫秒,详情请参见时间戳单位说明
end Long 1499162916 结束时间。单位为秒或毫秒,详情请参见时间戳单位说明。默认值为时序引擎服务器当前的时间。
queries Array 子查询数组,可以有一个或多个子查询数组。子查询数组参数说明请参见子查询数组参数
msResolution boolean true 时间戳单位返回为毫秒,取值:
  • true:时间戳单位返回为毫秒。
  • false:默认值,保留原时间戳单位。
说明 原时间戳单位为秒时该参数有效。
说明 时序引擎支持单时间点数据查询,您可以将开始时间和结束时间设置为相同的数值来查询单时间点数据。例如:"start":1356998400"end":1356998400

子查询数组参数说明如下。子查询数组中包括域查询参数。

名称 类型 是否必选 示例值 描述
metric String wind 指标名称。
fields List 域查询信息,可以有一个或多个域查询信息。域查询参数说明请参见域查询参数
limit Integer 1000 子查询返回数据点的最大数目。默认值为0,表示不限制返回数据点的数量。请求示例请参见limit和offset请求示例
说明 参数值不能为负数。是对多值返回结果进行分页查询。
offset Integer 500 子查询返回数据点的偏移量。默认值为0,表示不偏移返回的数据点。请求示例请参见limit和offset请求示例
说明 参数值不能为负数。是对多值返回结果进行分页查询。
tags Map 过滤指定的查询场景。
说明 与filters参数不能同时满足,filters和tags后设置的参数会生效。
filters List 过滤指定的查询场景。详细说明请参见Filters说明
说明 与tags参数不能同时满足,filters和tags后设置的参数会生效。

域查询参数说明如下。

名称 类型 是否必选 示例值 描述
aggregator String sum 聚合函数,详情请参见聚合(Aggregate)说明
field String speed 查询的域名。星号(*)表示查询条件中所有的域。
alias String speed_sum 域名在返回参数中的新名称。
downsample String 2s-last 时间维度降采样。参数说明请参见降采样Downsample说明
rate boolean true 是否计算指定指标值的增长速率。计算公式: Vt-Vt-1/t1-t-1。默认值为false。
dpValue String >=1000 根据条件过滤返回参数的数据点。支持大于号(>)、小于号(<)、等于号(=)、大于等于号(>=)、小于等于号(<=)和不等于号(!=)。请求示例请参见dpValue请求示例
说明 查询语句中包含的field总数不超过200个。 比如:某查询语句包括3个queries子查询数组,第一个子查询数组包含3个field, 第二个子查询数组包括2个field, 第三个子查询数组包含6个field,那么这个查询语句中field总数有3+2+6=11。

返回数据

查询成功的HTTP响应码为200,返回内容为JSON格式的数据。说明如下:

名称 描述
metric 指标名称。
columns 查询结果对应的列的名称。
tags tagv未做聚合的tag。
aggregateTags tagv做了聚合的tag。
values Tuple结构查询结果。

示例

请求语句: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"
                }
            ]
        }
    ]
}
            

返回示例

  • 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]
        ]
      }
    ]
                

时间戳单位说明

时间戳的单位可以是秒或毫秒。时序引擎会通过数值大小来判断时间戳的单位,规则如下:

说明 此规则适用于写入数据(/api/put/api/mput)和查询数据(/api/query/api/mquery)接口。
  • 时间戳数值在[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,+∞)区间表示非法时间戳。

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说明

当您查询的时间范围比较长,但只需要返回一定精度的数据时,可以使用Downsample参数进行设置,设置的查询格式如下。

<interval><units>-<aggregator>[-fill policy]          
格式中的参数说明。
  • interval:表示具体数值,比如5、60等。0或者all表示时间维度聚合为一个点。
  • units:表示时间单位,取值:
    • s表示秒。
    • m表示分。
    • h表示小时。
    • d表示天。
    • n表示月。
    • y表示年。
    说明 支持基于日历时间间隔的降采样。如果您使用日历时间,需要在时间单位 units 后添加c。例如1dc表示从当日零点到次日零点之间的24小时。
  • aggregator:表示降采样使用的算子及其说明如下表所示。
算子 描述
avg 平均值。
count 数据点数。
first 取第一个值。
last 取最后一个值。
min 最小值。
max 最大值。
sum 求和。
zimsum 求和。
rfirst 功能同first但降采样后返回的结果的时间戳是原始数据的时间戳,而非降采样对齐后的时间戳。
rlast 功能同last但降采样后返回的结果的时间戳是原始数据的时间戳,而非降采样对齐后的时间戳。
rmin 功能同min但降采样后返回的结果的时间戳是原始数据的时间戳,而非降采样对齐后的时间戳。
rmax 功能同max但降采样后返回的结果的时间戳是原始数据的时间戳,而非降采样对齐后的时间戳。
说明 当降采样的聚合算子指定为rfirst、rlast、rmin或rmax时,不能再在降采样表达式中指定Fill policy。

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

Fill Policy指定值 填充值
none 默认行为,不填值。
nan NaN。
null null。
zero 0。
linear 线性填充值。
previous 之前的一个值。
near 邻近的一个值。
after 之后的一个值。
fixed 用指定的一个固定填充值。
说明 将固定的填充值写在井号(#)后。填充值支持正负数。格式为<interval><units>-<aggregator>-fixed#<number>,比如:1h-sum-fixed#61h-avg-fixed#-8
降采样示例:1m-avg1h-sum-zero1h-sum-near
说明 在域查询参数中,downsample不是必选参数。您可以在查询时明确标明其值为null或空(””),例如{“downsample”: null}{“downsample”: “”},这样就不会触发数据点降采样。但是如果有一个域查询使用了 downsample参数,那么在同一子查询中的所有域查询参数都需要包括downsample参数并且采用同样的降采样区间。

聚合(Aggregate)说明

如果您设置了downsample参数,那么在降采样后会得到多条时间线的值,并且这些时间线的时间戳是对齐的,而聚合就是把多条时间线的值按各个对齐时刻聚合为一条时间线的结果。聚合时必须要求每条时间线在对应时刻都有值,如果某条时间线在某个时刻没有值,则会进行插值。
说明
  • 如果降采样后只有一条时间线,则不进行聚合运算。
  • 在域查询信息中,aggregator 是必须参数,但是可以通过{“aggregator ”: none}来指明不进行聚合运算。在时序引擎多值模型中不支持同一个请求查询语句有的域进行聚合运算,有的域不进行聚合运算。

插值:如果某条时间线某个精度区间没有值且没有使用Fill policy进行填值,而待聚合的其他时间线中有一条时间线在此精度区间有值,则会对本时间线的这个缺值精度区间进行插值。举例如下:降采样以及聚合条件为{"downsample": "10s-avg", "aggregator":"sum"},现在有两条时间线(line1和line2)按10s-avg做降采样之后的时间戳分别为:line 1:t+0, t+10, t+20, t+30 line 2:t+0, t+20, t+30。很明显line2缺少t+10时间点的值,在聚合前对line2的t+10这个时间点进行插值。插值的方法与聚合的算子有关,详见下面的算子列表。

算子 描述 插值方法
avg 平均值 线性插值(斜率拟合)。
count 数据点数 插0。
mimmin 最小值 插最大值。
mimmax 最大值 插最小值。
min 最小值 线性插值。
max 最大值 线性插值。
none 不做计算 插0。
sum 求和 线性插值。
zimsum 求和 插0。

Filters说明

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

  • 在指定tagk时指定filter:
    • tagk=*:对tagk下面的tagv做groupBy,相同的tagv做聚合运算。
    • tagk = tagv1|tagv2:分别对tagk下面的tagv1和tagv2数据做聚合运算。
  • 使用JSON格式指定filter:
    名字 类型 是否必选 示例值 描述
    type String
    • literal_or:web01丨web02
    • wildcard:*mysite.com
    filter类型,包括两种类型:
    • literal_or:表示分别对多个tagv做聚合运算,区分大小写。
    • wildcard:表示分别对满足通配符的tagv做聚合运算,区分大小写。
    tagk String host 指定tagk名称。
    filter String web01丨web02 filter表达式。
    groupBy Boolean false 是否对tagv做 groupBy。默认值为false。
    包含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"
                    }
                ]
            }
        ]
    }