单值数据查询_单值查询操作_HTTP API 参考_时序数据库 TSDB

请求路径和方法

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

请求内容

请求内容 JSON 格式

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

时间戳单位判断

时间戳的单位可以是秒或者毫秒。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/query) 两个接口。

单时间点数据查询

TSDB 支持单时间点数据查询。您可以将开始时间和结束时间设置为相同的数值。例如，"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冲突	无	-
hint	Map	否	查询 Hint 化	无	见查询 Hint 化说明

说明：

一个查询中能够包含的子查询个数最多不超过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。

    {
       "start":1346046400,
       "end":1347056500,
       "queries":[
          {
             "aggregator":"avg",
             "downsample":"2s-sum",
             "metric":"sys.cpu.0",
             "limit":"500",
             "offset":"1000",
             "tags":{
                "host":"localhost",
                "appName":"hitsdb"
             }
          }
       ]
    }

值过滤（dpValue）说明

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

示例

    {
       "start":1346046400,
       "end":1347056500,
       "queries":[
          {
             "aggregator":"avg",
             "downsample":"2s-sum",
             "metric":"sys.cpu.0",
             "dpValue":">=500",
             "tags":{
                "host":"localhost",
                "appName":"hitsdb"
             }
          }
       ]
    }

差值 (delta) 说明

当用户在子查询中指定差值算子的时候，TSDB返回的数据的”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

示例

    {
       "start":1346046400,
       "end":1347056500,
       "queries":[
          {
             "aggregator":"none",
             "downsample":"5s-avg",
             "delta":true,
             "deltaOptions":{
                 "counter":true,
                 "counterMax":100
             }
             "metric":"sys.cpu.0",
             "dpValue":">=50",
             "tags":{
                "host":"localhost",
                "appName":"hitsdb"
             }
          }
       ]
    }

降采样 (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 的查询示例

请求体：

    {
        "start": 1356998400,
        "end": 1356998460,
        "queries": [
            {
                "aggregator": "sum",
                "metric": "sys.cpu.0",
                "rate": "true",
                "tags": {
                    "host": "*",
                    "dc": "lga"
                }
            }
        ]
    }

包含 filter 的查询示例

请求体：

{
  "start": 1356998400,
  "end": 1356998460,
  "queries": [
    {
      "aggregator": "sum",
      "metric": "sys.cpu.0",
      "rate": "true",
      "filters": [
        {
          "type": "wildcard",
          "tagk": "host",
          "filter": "*",
          "groupBy": true
        },
        {
          "type": "literal_or",
          "tagk": "dc",
          "filter": "lga|lga1|lga2",
          "groupBy": false
        }
      ]
    }
  ]
}

查询结果说明

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

名称	描述
metric	指标名
tags	tagv 未做聚合的 tag
aggregateTags	tagv 做了聚合的 tag
dps	数据点对

响应结果示例：

[
    {
        "metric": "tsd.hbase.puts",
        "tags": {"appName": "hitsdb"},
        "aggregateTags": [
            "host"
        ],
        "dps": {
            "1365966001": 25595461080,
            "1365966061": 25595542522,
            "1365966062": 25595543979,
            "1365973801": 25717417859
        }
    }
]

查询 Hint 化说明

场景说明

该特性主要是提高查询速度。假设某一个 tags A 命中的时间线明显大于其他的 tags B 命中的时间线，则需要舍弃，避免捞取 tags A 的大量时间线之后，被 tagsB 小规模时间线交集后，结果集等于 tagsB。

格式说明

当前版本只支持 tagk 级别的查询索引限制
其中，0 表示不使用对应 tagk 的索引，反之 1 表示使用对应 tagk 的索引

查询示例

子查询级别

{
  "start": 1346846400,
  "end": 1346846400,
  "queries": [
    {
      "aggregator": "none",
      "metric": "sys.cpu.nice",
      "tags": {
        "dc": "lga",
        "host": "web01"
      },
      "hint": {
        "tagk": {
          "dc": 1
        }
      }
    }
  ]
}

整体查询级别

{
  "start": 1346846400,
  "end": 1346846400,
  "queries": [
    {
      "aggregator": "none",
      "metric": "sys.cpu.nice",
      "tags": {
        "dc": "lga",
        "host": "web01"
      }
    }
  ],
  "hint": {
    "tagk": {
      "dc": 1
    }
  }
}

异常情况

不可同时指定 0 和 1

{
  "start": 1346846400,
  "end": 1346846400,
  "queries": [
    {
      "aggregator": "none",
      "metric": "sys.cpu.nice",
      "tags": {
        "dc": "lga",
        "host": "web01"
      }
    }
  ],
  "hint": {
    "tagk": {
      "dc": 1,
      "host": 0
    }
  }
}

会返回如下报错信息：

{
    "error": {
        "code": 400,
        "message": "The value of hint should only be 0 or 1, and there should not be both 0 and 1",
        "details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
    }
}

不可指定除了 0 和 1 之外的值

{
  "start": 1346846400,
  "end": 1346846400,
  "queries": [
    {
      "aggregator": "none",
      "metric": "sys.cpu.nice",
      "tags": {
        "dc": "lga",
        "host": "web01"
      }
    }
  ],
  "hint": {
    "tagk": {
      "dc": 100
    }
  }
}

会返回如下报错信息：

{
    "error": {
        "code": 400,
        "message": "The value of hint can only be 0 or 1, and it is detected that '100' is passed in",
        "details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
    }
}

单值数据查询

请求路径和方法

请求内容

请求内容 JSON 格式

时间戳单位判断

单时间点数据查询

子查询 JSON 格式

查询示例

数据分页查询（Limit 和 Offset） 说明

示例

值过滤（dpValue） 说明

示例

差值 (delta) 说明

示例

降采样 (Downsample) 说明

Fill policy

降采样示例

聚合（Aggregate）说明

Filters 说明

Filter 类型说明

查询示例

不包含 filter 的查询示例

包含 filter 的查询示例

查询结果说明

查询 Hint 化说明

场景说明

格式说明

查询示例

子查询级别

整体查询级别

异常情况

不可同时指定 0 和 1

不可指定除了 0 和 1 之外的值

数据分页查询（Limit 和 Offset）说明

值过滤（dpValue）说明