全部产品
云市场

单值数据查询

更新时间:2019-12-27 10:56:10

请求路径和方法

请求路径 请求方法 描述
/api/query POST 查询数据

请求内容

请求内容 JSON 格式

名字 类型 是否必需 描述 默认值 举例
start Long 开始时间;单位为秒或者毫秒,判断规则详见下面的时间戳单位判断 1499158925
end Long 结束时间;单位为秒或者毫秒,判断规则详见下面的时间戳单位判断。默认值为 TSDB 服务器当前时间。 当前时间 1499162916
queries Array 子查询数组 子查询 JSON 格式

时间戳单位判断

本说明适用于读写数据(/api/put)和查询数据(api/query)两个接口。

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

  • 时间戳区间为 [4294768, 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]
  • 时间戳区间为 (-∞, 4294768) 和 (9999999999999, +∞):判断为非法时间戳区间

单时间点数据查询

TSDB 支持单时间点数据查询。您可以将开始时间和结束时间设置为相同的数值。例如,"start":1356998400"end":1356998400

子查询 JSON 格式

名称 类型 是否必需 描述 默认值 举例
aggregator String 聚合函数,详见下面的聚合(Aggregate)说明 sum
metric String 指标名 sys.cpu.nice
tags Map 指定标签过滤 {"host":"web01","dc":"lga"}
delta Boolean 是否计算指定指标值的差值; 计算公式:Vt - V{t-1} false true
limit Integer 数据分页,子查询返回数据点的最大数目 0 1000
downsample String 时间维度降采样 60m-avg

说明

  1. 一个查询中能够包含的子查询个数最多不超过 200 个
  2. 关于 tags 和 downsample 的详细信息,请见下面的相关说明

查询示例

请求: POST /api/query

请求体:

  1. {
  2. "start": 1346846400,
  3. "end": 1346846400,
  4. "queries": [
  5. {
  6. "aggregator": "sum",
  7. "metric": "sys.cpu.nice"
  8. },
  9. {
  10. "aggregator": "none",
  11. "metric": "sys.cpu.alter"
  12. }
  13. ]
  14. }

聚合(Aggregate)说明

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

插值

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

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

  1. line 1 t+0, t+10, t+20, t+30
  2. line 2 t+0, t+20, t+30

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

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

降采样(Downsample)说明

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

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

其中:

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

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

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

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

算子 描述
avg 平均值
count 数据点数
min 最小值
max 最大值
sum 求和

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": ""},这样就不会触发数据点降采样。