多值数据查询
多值模型数据查询 mquery
请求路径和方法
请求路径 | 请求方法 | 描述 |
---|---|---|
/api/mquery | POST | 查询数据 |
注意
- 多值模型数据和原来写入的单值模型数据不兼容。单值模型数据需要通过原有的 /api/put 进口进行写入。同时多值写入数据需要通过 /api/mquery 接口进行查询,单值写入的数据需要通过 /api/query 进行查询。
请求内容
名字 | 类型 | 是否必需 | 描述 | 默认值 | 举例 |
---|---|---|---|---|---|
start | Long | 是 | 开始时间;单位为秒或者毫秒,判断规则详见下面的时间戳单位判断。 | 无 | 1499158925 |
end | Long | 否 | 结束时间;单位为秒或者毫秒,判断规则详见下面的时间戳单位判断。默认值为 TSDB 服务器当前时间。 | 当前时间 | 1499162916 |
queries | Array | 是 | 子查询数组 | 无 | 见子查询说明 |
msResolution | boolean | 否 | 子查询数组 | false | 该参数只对原始数据单位是秒的查询生效;当该参数设置为 true 时,查询结果中的时间戳会转换为毫秒,否则仍保留原始时间单位;对于原始数据是毫秒的查询,返回结果中时间戳始终为毫秒。 |
时间戳单位判断
时间戳的单位可以是秒或者毫秒。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 格式
名称 | 类型 | 是否必需 | 描述 | 默认值 | 举例 |
---|---|---|---|---|---|
metric | String | 是 | 指标名 | 无 | wind |
fields | List | 是 | 域查询信息 | 无 | - |
limit | Integer | 否 | 数据分页,子查询返回数据点的最大数目 | 0 | 1000 |
offset | Integer | 否 | 数据分页,子查询返回数据点的偏移量 | 0 | 500 |
tags | Map | 否 | 指定查询标签过滤,和filters冲突 | 无 | - |
filters | List | 否 | 过滤器,和tags冲突 | 无 | - |
说明
- 一个查询中能够包含的总的Field个数最多不超过200个。 示例说明如下:
假设现有一个查询包含3个子查询,第一个子查询包含3个Field, 第二个子查询包括2个Field, 第三个子查询包含6个Field,那么这个查询包含的总的Field个数totalFields = 3 + 2 + 6 = 11, 即查询时需要保证totalFields不能大于200。
- tags 和 filters 都指定的场景下,后指定的过滤条件生效
域查询信息 JSON 格式
名称 | 类型 | 是否必需 | 描述 | 默认值 | 举例 |
---|---|---|---|---|---|
aggregator | String | 是 | 聚合函数,详见下面的聚合(Aggregate)说明。 | 无 | sum |
field | String | 是 | 域名称,”*”代表查询指标下所有域 | 无 | - |
alias | String | 否 | 域名称在返回结果中新名字 | ||
downsample | String | 否 | 时间维度降采样 | 无 | 60m-avg |
rate | Boolean | 否 | 是否计算指定指标值的增长速率;计算公式: Vt-Vt-1/t1-t-1 | false | true |
dpValue | String | 否 | 根据提供条件过滤返回数据点,支持”>”, “<”, “=”,”<=”, “>=”, “!=”。 | 无 | >=1000 |
说明:关于 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:降采样使用的算子及其说明如下表所示。
算子 | 描述 |
---|---|
avg | 平均值 |
count | 数据点数 |
first | 取第一个值 |
last | 取最后一个值 |
min | 最小值 |
max | 最大值 |
sum | 求和 |
zimsum | 求和 |
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 | 用指定的一个固定填充值(请参照下面示例) |
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” 这个时间点进行插值。插值的方法与聚合的算子有关,详见下面的算子列表。
算子 | 描述 | 插值方法 |
---|---|---|
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 | 是 | filter 类型,详见下面说明 | 无 | literal_or |
tagk | String | 是 | 指定 tagk 名 | 无 | host |
filter | String | 是 | filter 表达式 | 无 | web01丨web02 |
groupBy | Boolean | 否 | 是否对 tagv 做 groupBy | false | false |
Filter 类型说明
名称 | filter 举例 | 描述 |
---|---|---|
literal_or | web01丨web02 | 分别对多个 tagv 做聚合,区分大小写 |
wildcard | *mysite.com | 分别对满足通配符的 tagv 做聚合,区分大小写 |
查询示例
包含 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 格式数据。说明如下:
名称 | 描述 |
---|---|
metric | 指标名 |
columns | 查询结果对应的列的名称 |
tags | tagv 未做聚合的 tag |
aggregateTags | tagv 做了聚合的 tag |
values | Tuple结构查询结果 |
响应结果示例:
- 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]
]
}
]
版权声明
本文仅代表作者观点,不代表本站立场。
本文系作者授权发表,未经许可,不得转载。
评论