单值查询数据

请求路径和方法

请求路径： /api/query

请求方法：POST

描述：查询数据

请求内容（JSON 格式）

时间戳单位判断

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

• 时间戳区间为 [4294968,4294967295]：判断为秒，表示的时间区间为： [1970-02-20 01:02:48, 2106-02-07 14:28:15]。

• 时间戳区间为 [4294967296,9999999999999]：判断为毫秒，表示的时间区间为：[1970-02-20 01:02:47.296, 2286-11-21 01:46:39.999]。

• 时间戳区间为 （-∞,4294968）和（9999999999999,+∞）：判断为非法时间戳区间。

单时间点数据查询

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

子查询（JSON 格式）

查询示例

请求： 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，代表不偏移返回的数据点。

示例

返回第 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 如下所示：

示例

    {
       "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 代表年。

  说明

  • 默认按照时间戳取模对齐，即"对齐时间戳 = 数据时间戳 - （数据时间戳 % interval）"。

  • 支持基于日历时间间隔的降采样。要使用日历界限，您需要在时间单位 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 这个时间点进行插值。插值的方法与聚合的算子有关，详见下面的算子列表。

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	*.example.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 级别的查询索引限制（hint 下的 tagk 是固定写法）。

• 其中， 0 表示不使用对应 tagk 的索引，反之 1 表示使用对应 tagk 的索引。

版本说明

从 v2.6.1 版本开始支持 hint 特性。

查询示例

子查询级别

{
  "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=[])"
}

时序异常检测 (forecasting) 说明

根据时间序列已有数据作为训练集，通过 AI 算法发现数据趋势和周期，从而预测该时间序列在未来一段时间的数据点。查询格式如下：

<AlgorithmName>-<ForecastPointCount>[-<ForecastPolicy>]                         

其中：

• AlgorithmName：算法名称。 目前支持 arima，holtwinters 算法。

• ForecastPointCount：预测未来数据点的个数。Integer 类型的数据。如 2 代表预测未来 2 个点。

• ForecastPolicy：预测策略。 算法不同代表含义也不同。

  • 当 AlgorithmName 是 arima 时，ForecastPolicy 格式如下：

    说明

    • Delta 代表差分阶数，默认 1。通过增大差分可以调节数据波动，使数据趋于稳定。

    • Seasonality 代表季节周期， 默认 1。当数据按照周期规律波动时，可以通过设置 seasonality 调整预测周期。比如数据每 10 个数据点，波动一次，则 seasonality 就设置成 10。

  • 当 AlgorithmName 是 holtwinters 时，ForecastPolicy 格式如下：

    说明

    Seasonality 代表季节周期， 默认 1。当数据按照周期规律波动时，可以通过设置 seasonality 调整预测周期。比如数据每 10 个数据点，波动一次，则 seasonality 就设置成 10。

预测样例

示例： arima-1，arima-48-1-48，holtwinters-1-1。假设数据是

[
      "metric": "sys.cpu.nice",
      "tags": {
          "dc": "lga",
          "host": "web00"
      "aggregateTags": [],
      "dps": {
          "1346837400": 1,
          "1346837401": 2,
          "1346837402": 3,
          "1346837403": 4,
          "1346837404": 5,
          "1346837405": 6,
          "1346837406": 7,
          "1346837407": 8,
          "1346837408": 9,
          "1346837409": 10,
          "1346837410": 11,
          "1346837411": 12
]

查询

{
     "start":1346837400,
     "end": 1346847400,
     "queries":[
           "aggregator":"none",
           "metric":"sys.cpu.nice",
           "forecasting" : "arima-1"
}

预测后的结果是

[
        "metric": "sys.cpu.nice",
        "tags": {
            "dc": "lga",
            "host": "web00"
        "aggregateTags": [],
        "dps": {
            "1346837400": 1,
            "1346837401": 2,
            "1346837402": 3,
            "1346837403": 4,
            "1346837404": 5,
            "1346837405": 6,
            "1346837406": 7,
            "1346837407": 8,
            "1346837408": 9,
            "1346837409": 10,
            "1346837410": 11,
            "1346837411": 12,
            "1346837412": 13
]

时序预测 (abnormaldetect) 说明

根据时间序列已有数据作为训练集，通过 AI 算法发现数据趋势和周期，从而预测该时间序列在未来一段时间的数据点。查询格式如下：

<AlgorithmName>[-<Sigma>-<NP>-<NS>-<NT>-<NL>]

目前异常检测只支持一种算法：stl 方法。对于参数调参不太了解的建议选择默认参数。如果用户对 STL 算法比较熟悉，可以通过额外调参获得 更好的预测结果。异常检测的完整参数有 6 个，分别是 AlgorithmName-Sigma-NP-NS-NT-NL 示例如下 stl-5-5-7-0-0 ，参数通过 - 分隔。每个参数代表的含义如下：

• Sigma：异常点检测，如果数据点与均值的差值绝对值在 3 倍标准差外，则认为是异常点。一般为 3.0。

• NP ：每个周期包含的点数，根据周期判断。

• NS： 季节平滑参数。

• NT： 趋势平滑参数。

• NL： 低通滤波平滑参数

预测样例

示例 1：

"abnormaldetect”: “stl”,

示例 2：

"abnormaldetect”: “stl-5-5-7-0-0”,

查询样例

{
       "start":1346836400,
       "end":1346946400,
       "queries":[
             "aggregator": "none",
             "metric":     "sys.cpu.nice",
             "abnormaldetect":  "stl-5-5-7-0-0",
             "filters": [
                "type":   "literal_or",
                "tagk":   "dc",
                "filter": "lga",
                "groupBy": false
                "type":   "literal_or",
                "tagk":   "host",
                "filter": "web00",
                "groupBy": false
}

输出样例

TSDB 的异常检测输出的是一个链表， 该链表 layout 固定，格式如下：

[srcValue, upperValue, lowerValue, predictValue, isAbnormal]

• srcValue：原始数据的 value

• upperValue：数据值的上界

• lowerValue：数据值的下界

• predictValue：stl 计算后预测值

• isAbnormal：标记原始 value 是否异常，0 代表正常， 1 代表异常。

  [
          "metric": "sys.cpu.nice",
          "tags": {
              "dc": "lga",
              "host": "web00"
          "aggregateTags": [],
          "dps": {
              "1346837400": [
                  1.0000000000000049,
                  0.9999999999999973,
                  1.0000000000000013,
              "1346837401": [
                  2.0000000000000036,
                  1.9999999999999958,
                  1.9999999999999998,
              "1346837402": [
                  3.0000000000000036,
                  2.9999999999999956,
              "1346837403": [
                  4.0000000000000036,
                  3.9999999999999956,
              "1346837404": [
                  5.0000000000000036,
                  4.9999999999999964,
              "1346837405": [
                  6.000000000000002,
                  5.999999999999995,
                  5.999999999999998,
              "1346837406": [
                  7.0000000000000036,
                  6.9999999999999964,
              "1346837407": [
                  8.000000000000004,
                  7.9999999999999964,
              "1346837408": [
                  9.000000000000004,
                  8.999999999999996,
              "1346837409": [
                  10.000000000000004,
                  9.999999999999996,
              "1346837410": [
                  11.000000000000005,
                  10.999999999999998,
                  11.000000000000002,
              "1346837411": [
                  12.000000000000004,
                  11.999999999999996,