请求路径和方法

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

请求内容 JSON 格式

名字 类型 是否必需 描述 默认值 举例
start Long 开始时间;单位为秒或者毫秒,判断规则详见下面的时间戳单位判断。 1499158925
end Long 结束时间;单位为秒或者毫秒,判断规则详见下面的时间戳单位判断。默认值为时序引擎服务器当前时间。 当前时间 1499162916
queries Array 子查询数组 见子查询说明
msResolution boolean 子查询数组 false 该参数只对原始数据单位是秒的查询生效;当该参数设置为 true 时,查询结果中的时间戳会转换为毫秒,否则仍保留原始时间单位;对于原始数据是毫秒的查询,返回结果中时间戳始终为毫秒。

时间戳单位判断

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

  • 时间戳区间为 [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/query) 两个接口。

单时间点数据查询

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

子查询 JSON 格式

名称 类型 是否必需 描述 默认值 举例
aggregator String 聚合函数,详见下面的聚合(Aggregate)说明。 sum
metric String 指标名 sys.cpu0
rate Boolean 是否计算指定指标值的增长速率;计算公式: Vt-Vt-1/t1-t-1 false true
delta Boolean 是否计算指定指标值的差值; 计算公式: Vt-Vt-1 false true
limit Integer 数据分页,子查询返回数据点的最大数目 0 1000
offset Integer 数据分页,子查询返回数据点的偏移量 0 500
dpValue String 根据提供条件过滤返回数据点,支持”>”, “<”, “=”,”<=”, “>=”, “!=”。 >=1000
preDpValue String 根据提供的条件在扫描原始数据点时进行过滤,支持”>”, “<”, “=”,”<=”, “>=”, “!=”。注意:它与“dpValue”的不同在于前者是对查询完成后计算的结果进行值过滤;后者是在存储的数据点进行扫描时进行值过滤,使得不满足过滤条件的数据点根本不会加入查询计算。 >=1000
downsample String 时间维度降采样 60m-avg
tags Map 指定标签过滤,和filters冲突 -
filters List 过滤器,和tags冲突 -
说明
  • 一个查询中能够包含的子查询个数最多不超过200个。
  • tags 和 filters 都指定的场景下,后指定的过滤条件生效。
  • 关于 limit、dpValue、downsample、tags 和 filters 的详细信息请见下面的相关说明

查询示例

请求:POST/api/query

请求体:

{
  "start": 1356998400,
  "end": 1356998460,
  "queries": [
    {
      "aggregator": "sum",
      "metric": "sys.cpu.0"
    },
    {
      "aggregator": "sum",
      "metric": "sys.cpu.1"
    }
  ]
}

数据分页查询(Limit 和 Offset) 说明

Limit:子查询返回数据点的最大数目。默认值是 0,代表不限制返回点数量。

Offset: 子查询返回数据点的偏移量。默认值也是 0,代表不偏移返回的数据点。

注意 limit 和 offset 不能为负数。

示例

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

1.    {
2.       "start":1346046400,
3.       "end":1347056500,
4.       "queries":[
5.          {
6.             "aggregator":"avg",
7.             "downsample":"2s-sum",
8.             "metric":"sys.cpu.0",
9.             "limit":"500",
10.             "offset":"1000",
11.             "tags":{
12.                "host":"localhost",
13.                "appName":"hitsdb"
14.             }
15.          }
16.       ]
17.    }

值过滤(dpValue) 说明

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

1.    {
2.       "start":1346046400,
3.       "end":1347056500,
4.       "queries":[
5.          {
6.             "aggregator":"avg",
7.             "downsample":"2s-sum",
8.             "metric":"sys.cpu.0",
9.             "dpValue":">=500",
10.            "tags":{
11.                "host":"localhost",
12.                "appName":"hitsdb"
13.             }
14.          }
15.       ]
16.    }

差值 (delta) 说明

当用户在子查询中指定差值算子的时候,时序引擎返回的数据的”dps”中的key-value对的value值将是计算所得的差值。需要注意的是,如果未指定差值时返回的”dps”中有 n 个key-value对,那么计算完差值后返回的”dps”中将只包含 n-1 个key-value对(第一个key-value对因无法求差值将被舍去)。差值算子对于Downsample后的值也同样适用。

此外,用户指定了差值算子时,还可以进一步在子查询中指定 “deltaOptions” 来对求差值的行为进行进一步控制。当前支持的 “deltaOptions” 如下所示:

名称 类型 是否必需 描述 默认值 举例
counter Boolean 当该标记位被指定时则表示假定用于计算差值的指标值被用户视作是一个类似计数器的单调递增(或递减)的累计值(但服务器并不会加以check)。 false true
counterMax Integer 当counter被设置为true时, 该值用于指定差值的阈值。当差值的绝对值超过该阈值时将被视作异常值;该值不指定时则对差值不设阈值。 100
dropReset Boolean 该标记位需要与上述 counterMax 结合使用。当通过指定counterMax 后计算出了异常的差值,dropReset决定是否要直接丢弃异常的差值。若指定为true,则异常值直接被丢弃;若指定为false(默认情况),则异常值被重置为零。 false true

示例

1.    {
2.       "start":1346046400,
3.       "end":1347056500,
4.       "queries":[
5.          {
6.             "aggregator":"none",
7.             "downsample":"5s-avg",
8.             "delta":true,
9.             "deltaOptions":{
10.                 "counter":true,
11.                 "counterMax":100
12.             }
13.             "metric":"sys.cpu.0",
14.             "dpValue":">=50",
15.             "tags":{
16.                "host":"localhost",
17.                "appName":"hitsdb"
18.             }
19.          }
20.       ]
21.    }

降采样 (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 最大值
median 求中位数
sum 求和
zimsum 求和
rfirst 功能同first但降采样后返回的结果的时间戳是原始数据的时间戳;而非降采样对齐后的时间戳
rlast 功能同last但降采样后返回的结果的时间戳是原始数据的时间戳;而非降采样对齐后的时间戳
rmin 功能同min但降采样后返回的结果的时间戳是原始数据的时间戳;而非降采样对齐后的时间戳
rmax 功能同max但降采样后返回的结果的时间戳是原始数据的时间戳;而非降采样对齐后的时间戳
说明 当降采样的聚合算子指定为rfirst, rlast, rmin或rmax时, 不能再在降采样表达式中指定fill policy。
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”: “”},这样就不会触发数据点降采样。

聚合(Aggregate)说明

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

插值

如果某条时间线某个精度区间没有值且没有使用 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 的查询示例

请求体

1.    {
2.        "start": 1356998400,
3.        "end": 1356998460,
4.        "queries": [
5.            {
6.                "aggregator": "sum",
7.                "metric": "sys.cpu.0",
8.                "rate": "true",
9.                "tags": {
10.                    "host": "*",
11.                    "dc": "lga"
12.                }
13.            }
14.        ]
15.    }
包含 filter 的查询示例

请求体:

1. {
2.  "start": 1356998400,
3.  "end": 1356998460,
4.  "queries": [
5.    {
6.      "aggregator": "sum",
7.      "metric": "sys.cpu.0",
8.      "rate": "true",
9.      "filters": [
10.        {
11.          "type": "wildcard",
12.          "tagk": "host",
13.          "filter": "*",
14.          "groupBy": true
15.        },
16.        {
17.          "type": "literal_or",
18.          "tagk": "dc",
19.          "filter": "lga|lga1|lga2",
20.          "groupBy": false
21.        }
22.      ]
23.    }
24.  ]
25. }

查询结果说明

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

名称 描述
metric 指标名
tags tagv 未做聚合的 tag
aggregateTags tagv 做了聚合的 tag
dps 数据点对
响应结果示例:
1.  [
2.    {
3.        "metric": "tsd.hbase.puts",
4.        "tags": {"appName": "hitsdb"},
5.        "aggregateTags": [
6.            "host"
7.        ],
8.        "dps": {
9.            "1365966001": 25595461080,
10.           "1365966061": 25595542522,
11.           "1365966062": 25595543979, 
12.           "1365973801": 25717417859 
13.       } 
14.   }
15.  ]