全部产品
弹性计算 会员服务 网络 安全 移动云 数加·大数据分析及展现 数加·大数据应用 管理与监控 云通信 阿里云办公 培训与认证 更多
存储与CDN 数据库 域名与网站(万网) 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网 智能硬件
高性能时间序列数据库 HiTSDB

查询数据

更新时间:2018-04-01 20:04:12

请求路径和方法

请求路径 请求方法 描述
/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 聚合函数,详见下面的聚合(Aggregate)说明 sum
metric String 指标名 sys.cpu0
rate Boolean 默认为 false,是否计算返回相邻点的斜率,例如当查询值为总请求量,需要查看其 QPS 的时候使用。 false 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 代表天

  • aggregator :降采样使用的算子及其说明如下表所示。
算子 描述 插值方法
avg 平均值 线性插值(斜率拟合)
count 数据点数 插 0
first 取第一个值 -
last 取最后一个值 -
mimmin 最小值 插最大值
mimmax 最大值 插最小值
min 最小值 线性插值
max 最大值 线性插值
sum 求和 线性插值
zimsum 求和 插 0
  • 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

降采样示例

示例:1m-avg,1h-sum-zero

注意:查询时,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. ]
本文导读目录