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

请求路径和方法

请求路径：/api/query

请求方法：POST

描述：查询数据

请求内容（JSON 格式）

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

时间戳单位判断

时间戳的单位可以是秒或者毫秒。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,+∞)：判断为非法时间戳区间。

说明

适用于写入数据 (/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化说明
forecasting	String	否	数据预测。	无	见查询forecasting说明
abnormaldetect	String	否	数据预测。	无	见查询abnormaldetect说明

说明

一个查询中能够包含的子查询个数最多不超过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区间向前后多包含一个时间窗口。例如，指定时间戳范围为[1346846401,1346846499] ，指定的interval为5m，则查询真实的时间戳范围为[1346846101,1346846799]。

其中：

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这个时间点进行插值。插值的方法与聚合的算子有关，详见下面的算子列表。

算子	描述	插值方法
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级别的查询索引限制（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,
                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
            ]
        }
    }
]