全部产品
存储与CDN 数据库 安全 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网 钉钉智能硬件
高性能时间序列数据库 HiTSDB

查询数据

更新时间:2017-12-11 15:16:10

请求路径和方法

请求路径 请求方法 说明
/api/query POST 查询数据

请求内容

请求内容 JSON 格式

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

时间戳说明

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

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

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

子查询 JSON 格式

名字 类型 是否必需 描述 举例
aggregator String 必需 聚合函数,见下面说明 sum
metric String 必需 指标名 sys.cpu0
rate Boolean 可选 默认为 false,是否计算返回相邻点的斜率,例如当查询值为总请求量,需要查看其 QPS 的时候使用 true
downsample String 可选 时间维度降精度采样 60m-avg
tags Map 可选 指定 tag -
filters List 可选 过滤器 -

说明:关于 downsample、tags 和 filters 的详细信息请见下面的说明内容。

查询示例

请求: POST /api/query

请求体:

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

 

降精度 (Downsample) 说明

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

  1. 格式:<interval><units>-<aggregator>[-fill policy]
  • interval:指数值,如5,60等,特殊的”0all”表示时间维度聚合为一个点

  • units:s 代表秒,m 代表分,h 代表小时,d 代表天

  • 插值描述:

    在计算时当遇到缺点,会采取插值的方法补充,插值发生在降精度以及聚合2个阶段。

    • 比如降精度时 downsample 为10秒(10s),0、1、2、4、8的数据点做计算时,会插入3、5、6、7、9时刻的值。

    • 比如聚合时有2条时间线,line1:0,10,20,30,line2:0,20,30,第二条时间线缺10这个时刻的值,那么会进行插值。

fill policy 插值描述:

名称 描述
none 默认行为,即不插值
nan double 无意义值
null double 无意义值时用 null 代替
zero 插入0

Aggregator 说明

Aggregator 在降精度和多条时间线聚合时使用。

算子 描述 插值方法
avg 平均值 线性插值(斜率拟合)
count 数据点数 插0
dev 标准差 线性插值
first 取第一个值,仅用于降精度 downsampling -
last 取最后一个值,仅用于降精度 downsampling -
mimmin 最小值 插最大值
mimmax 最大值 插最小值
min 最小值 线性插值
max 最大值 线性插值
none 不做计算 插0
p50 50%的值都大于 线性插值
p75 75%的值都大于 线性插值
p90 90%的值都大于 线性插值
p95 95%的值都大于 线性插值
p99 99%的值都大于 线性插值
p999 999%的值都大于 线性插值
sum 求和 线性插值
zimsum 求和 插0

Downsample 举例: 1m-avg,1h-sum-zero

Filters 说明

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

  • 在指定 tagk 时指定 filter:

    • tagk=*:对 tagk 下面的 tagv 做 groupby,相同的 tagv 做聚合。

    • tagk=tagv1|tagv2: 分别对 tagk 下面的 tagv1 和 tagv2 数据做聚合。

  • 使用 JSON 格式指定 filter:
名字 类型 是否必选 描述 举例
type String 必选 filter 类型,见下面说明 regexp
tagk String 必选 指定 tagk 名 host
filter String 必选 filter 表达式 web.*.mysite.com
groupBy Boolean 可选 是否对 tagv 做 groupBy,默认为 false false

一个典型的 filter 数据:

  1. {
  2. "type": "regexp",
  3. "filter": "web[0-9]+.lax.mysite.com",
  4. "tagk": "host",
  5. "groupBy": false
  6. }

Filter 类型说明

名称 filter 举例 说明
literal_or web01丨 web02 分别对多个 tagv 做聚合,区分大小写
not_literal_or web01丨 web02 分别对不是指定 tagv 做聚合,区分大小写
wildcard *mysite.com 分别对满足通配符的 tagv 做聚合,区分大小写
regexp web[0-9].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. ]
本文导读目录