单值数据查询

请求路径和方法

请求内容

请求内容 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

请求体：

```json{ “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
        }
    }
]