单值数据查询

请求路径和方法

请求内容

请求内容 JSON 格式

时间戳单位判断

时间戳的单位可以是秒或者毫秒。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 格式

说明：

1. 一个查询中能够包含的子查询个数最多不超过200个
2. tags 和 filters 都指定的场景下，后指定的过滤条件生效
3. 关于 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” 如下所示：

示例

    {
       "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：降采样使用的算子及其说明如下表所示。

说明：

• 当降采样的聚合算子指定为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 与具体填充值的对应如下表所示。

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：

Filter 类型说明

查询示例

不包含 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": "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-Seasonality

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

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

    Seasonality

    • 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,
                1.0000000000000049,
                0.9999999999999973,
                1.0000000000000013,
                0
            ],
            "1346837401": [
                2,
                2.0000000000000036,
                1.9999999999999958,
                1.9999999999999998,
                0
            ],
            "1346837402": [
                3,
                3.0000000000000036,
                2.9999999999999956,
                3,
                0
            ],
            "1346837403": [
                4,
                4.0000000000000036,
                3.9999999999999956,
                4,
                1
            ],
            "1346837404": [
                5,
                5.0000000000000036,
                4.9999999999999964,
                5,
                0
            ],
            "1346837405": [
                6,
                6.000000000000002,
                5.999999999999995,
                5.999999999999998,
                0
            ],
            "1346837406": [
                7,
                7.0000000000000036,
                6.9999999999999964,
                7,
                1
            ],
            "1346837407": [
                8,
                8.000000000000004,
                7.9999999999999964,
                8,
                0
            ],
            "1346837408": [
                9,
                9.000000000000004,
                8.999999999999996,
                9,
                0
            ],
            "1346837409": [
                10,
                10.000000000000004,
                9.999999999999996,
                10,
                0
            ],
            "1346837410": [
                11,
                11.000000000000005,
                10.999999999999998,
                11.000000000000002,
                0
            ],
            "1346837411": [
                12,
                12.000000000000004,
                11.999999999999996,
                12,
                0
            ]
        }
    }
]