全部产品
云市场
云游戏

单值数据查询

更新时间:2020-08-07 23:11:36

请求路径和方法

请求路径 请求方法 描述
/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 化说明

说明

  1. 一个查询中能够包含的子查询个数最多不超过200个
  2. tags 和 filters 都指定的场景下,后指定的过滤条件生效
  3. 关于 limit、dpValue、downsample、tags 和 filters 的详细信息请见下面的相关说明。

查询示例

请求: POST/api/query

请求体:

  1. {
  2. "start": 1356998400,
  3. "end": 1356998460,
  4. "queries": [
  5. {
  6. "aggregator": "sum",
  7. "metric": "sys.cpu.0"
  8. },
  9. {
  10. "aggregator": "sum",
  11. "metric": "sys.cpu.1"
  12. }
  13. ]
  14. }
  15. &nbsp;
  16. ## 数据分页查询(Limit Offset 说明
  17. **Limit**::子查询返回数据点的最大数目。默认值是 0,代表不限制返回点数量。
  18. **Offset**: 子查询返回数据点的偏移量。默认值也是 0,代表不偏移返回的数据点。
  19. **注意:**limit offset 不能为负数。
  20. ###示例
  21. 返回第 1001 1500 的数据点,则 limit 设为 500offset 设为 1000
  22. {
  23. "start":1346046400,
  24. "end":1347056500,
  25. "queries":[
  26. {
  27. "aggregator":"avg",
  28. "downsample":"2s-sum",
  29. "metric":"sys.cpu.0",
  30. "limit":"500",
  31. "offset":"1000",
  32. "tags":{
  33. "host":"localhost",
  34. "appName":"hitsdb"
  35. }
  36. }
  37. ]
  38. }
  39. &nbsp;
  40. ## 值过滤(dpValue 说明
  41. 根据用户设置的数值限制条件,过滤最终的返回数据点。支持 ">", "<", "=", "<=", ">=", "!="
  42. ###示例
  43. {
  44. "start":1346046400,
  45. "end":1347056500,
  46. "queries":[
  47. {
  48. "aggregator":"avg",
  49. "downsample":"2s-sum",
  50. "metric":"sys.cpu.0",
  51. "dpValue":">=500",
  52. "tags":{
  53. "host":"localhost",
  54. "appName":"hitsdb"
  55. }
  56. }
  57. ]
  58. }
  59. &nbsp;
  60. ## 差值 (delta) 说明
  61. 当用户在子查询中指定差值算子的时候,TSDB返回的数据的"dps"中的key-value对的value值将是计算所得的差值。需要注意的是,如果未指定差值时返回的"dps"中有 n key-value对,那么计算完差值后返回的"dps"中将只包含 n-1 key-value对(第一个key-value对因无法求差值将被舍去)。差值算子对于Downsample后的值也同样适用。
  62. 此外,用户指定了差值算子时,还可以进一步在子查询中指定 "deltaOptions" 来对求差值的行为进行进一步控制。当前支持的 "deltaOptions" 如下所示:
  63. 名称|类型|是否必需|描述|默认值|举例
  64. -|-|-|-|-
  65. counter | Boolean | | 当该标记位被指定时则表示假定用于计算差值的指标值被用户视作是一个类似计数器的单调递增(或递减)的累计值(但服务器并不会加以check) | false | true
  66. counterMax | Integer | | counter被设置为true时, 该值用于指定差值的阈值。当差值的绝对值超过该阈值时将被视作异常值;该值不指定时则对差值不设阈值 | | 100
  67. dropReset | Boolean | | 该标记位需要与上述 counterMax 结合使用。当通过指定counterMax 后计算出了异常的差值,dropReset决定是否要直接丢弃异常的差值。若指定为true,则异常值直接被丢弃;若指定为false(默认情况),则**异常值被重置为零** | false | true
  68. ###示例
  69. {
  70. "start":1346046400,
  71. "end":1347056500,
  72. "queries":[
  73. {
  74. "aggregator":"none",
  75. "downsample":"5s-avg",
  76. "delta":true,
  77. "deltaOptions":{
  78. "counter":true,
  79. "counterMax":100
  80. }
  81. "metric":"sys.cpu.0",
  82. "dpValue":">=50",
  83. "tags":{
  84. "host":"localhost",
  85. "appName":"hitsdb"
  86. }
  87. }
  88. ]
  89. }
  90. &nbsp;
  91. ## 降采样 (Downsample) 说明
  92. 当查询的时间范围比较长,只需返回一定精度的数据时使用。查询格式如下:
  93. <interval><units>-<aggregator>[-fill policy]
  94. 该查询格式可称作**降采样表达式**
  95. 其中:
  96. - **interval:**指数值,如 560 等,特殊的“0all”表示时间维度聚合为一个点。
  97. - **units:**s 代表秒,m 代表分,h 代表小时,d 代表天,n 代表月,y 代表年。
  98. **说明:**支持基于日历时间间隔的降采样。要使用日历界限,您需要在时间单位 **units** 后添加一个``c``。例如,``1dc``代表从当日零点到次日零点之间的 24 小时。
  99. - **aggregator:**
  100. 降采样使用的算子及其说明如下表所示。
  101. 算子|描述
  102. -|-
  103. avg|平均值
  104. count|数据点数
  105. first|取第一个值
  106. last|取最后一个值
  107. min|最小值
  108. max|最大值
  109. median|求中位数
  110. sum|求和
  111. zimsum|求和
  112. rfirst|功能同`first`</br>但降采样后返回的结果的时间戳是原始数据的时间戳;</br>而非降采样对齐后的时间戳
  113. rlast|功能同`last`</br>但降采样后返回的结果的时间戳是原始数据的时间戳;</br>而非降采样对齐后的时间戳
  114. rmin|功能同`min`</br>但降采样后返回的结果的时间戳是原始数据的时间戳;</br>而非降采样对齐后的时间戳
  115. rmax|功能同`max`</br>但降采样后返回的结果的时间戳是原始数据的时间戳;</br>而非降采样对齐后的时间戳
  116. **说明**:
  117. * 当降采样的聚合算子指定为*rfirst*, *rlast*, *rmin*或*rmax*时, 不能再在降采样表达式中指定fill policy
  118. ###Fill policy
  119. Fill policy 即填值。降采样先把所有时间线按照指定精度切分,并把每个降采样区间内的数据做一次运算,降采样后如果某个精度区间没有值,fill policy 可以指定在这个时间点填充具体的值。比如某条时间线降采样后的时间戳为:t+0, t+20, t+30,此时如果不指定 fill policy,只有 3 个值,如果指定了 fill policy null,此时间线会有 4 个值,其中 t+10 时刻的值为 null
  120. Fill policy 与具体填充值的对应如下表所示。
  121. Fill Policy |填充值
  122. -|-
  123. none|默认行为,不填值
  124. nan|NaN
  125. null|null
  126. zero| 0
  127. linear|线性填充值
  128. previous|之前的一个值
  129. near | 邻近的一个值
  130. after | 之后的一个值
  131. fixed|用指定的一个固定填充值(请参照下面示例)
  132. **Fixed Fill Policy**
  133. 使用方法:将固定的填充值写到 "#"之后。填充值支持正负数。格式如下:
  134. <interval><units>-<aggregator>-fixed#<number>
  135. **示例**:1h-sum-fixed#6 1h-avg-fixed#-8
  136. ###降采样示例
  137. 示例:1m-avg1h-sum-zero1h-sum-near
  138. **注意**:查询时,downsample 不是必要条款。您甚至可以在查询时明确标明其值为 null 或者空(""),例如:{"downsample": null} 或者 {"downsample": ""},这样就不会触发数据点降采样。
  139. &nbsp;
  140. ## 聚合(Aggregate)说明
  141. 在降采样后会得到多条时间线的值,并且这些时间线的时间戳是对齐的,而聚合就是把多条时间线的值按各个对齐时刻聚合为一条时间线的结果(注意:如果只有一条时间线,则不进行聚合)。聚合时必须要求每条时间线在对应时刻都有值,如果某条时间线在某个时刻没有值,则会进行插值,插值描述如下。
  142. **插值**
  143. 如果某条时间线某个精度区间没有值且没有使用 fill policy 进行填值,而待聚合的其他时间线中有一条时间线在此精度区间有值,则会对本时间线的这个缺值精度区间进行插值。
  144. 例如:降采样以及聚合条件为{"downsample": "10s-avg", "aggregator": "sum"}
  145. ,有两条时间线需要使用 sum 聚合,按 10s-avg 做降采样后的这两条时间线有值的时间戳分别为:
  146. line 1 t+0, t+10, t+20, t+30
  147. <br/>
  148. line 2 t+0, t+20, t+30
  149. 第二条时间线 line 2 t+10 这个时刻的值,那么在聚合前会对 line 2 t+10 这个时间点进行插值。插值的方法与聚合的算子有关,详见下面的算子列表。
  150. 算子|描述|插值方法
  151. -|-|-
  152. avg|平均值|线性插值(斜率拟合)
  153. count|数据点数|插 0
  154. mimmin|最小值|插最大值
  155. mimmax|最大值|插最小值
  156. min|最小值|线性插值
  157. max|最大值|线性插值
  158. none|不做计算|插 0
  159. sum|求和|线性插值
  160. zimsum|求和|插 0
  161. &nbsp;
  162. ## Filters 说明
  163. 有以下两种方法可以指定 filter
  164. - 在指定 tagk 时指定 filter
  165. - **tagk = ***:对 tagk 下面的 tagv groupBy,相同的 tagv 做聚合。
  166. - **tagk = tagv1|tagv2**: 分别对 tagk 下面的 tagv1 tagv2 数据做聚合。
  167. - 使用 JSON 格式指定 filter
  168. 名字|类型|是否必需|描述|默认值|举例
  169. -|-|-|-|-
  170. type|String|是|filter 类型,详见下面说明|无|literal_or
  171. tagk|String|是|指定 tagk 名|无|host
  172. filter|String|是|filter 表达式|无|web01web02
  173. groupBy|Boolean|否|是否对 tagv groupBy|false|false
  174. ### Filter 类型说明
  175. 名称|filter 举例|描述
  176. -|-|-
  177. literal_or|web01 web02|分别对多个 tagv 做聚合,区分大小写
  178. wildcard|*mysite.com|分别对满足通配符的 tagv 做聚合,区分大小写
  179. ### 查询示例
  180. #### 不包含 filter 的查询示例
  181. **请求体:**
  182. {
  183. "start": 1356998400,
  184. "end": 1356998460,
  185. "queries": [
  186. {
  187. "aggregator": "sum",
  188. "metric": "sys.cpu.0",
  189. "rate": "true",
  190. "tags": {
  191. "host": "*",
  192. "dc": "lga"
  193. }
  194. }
  195. ]
  196. }
  197. #### 包含 filter 的查询示例
  198. **请求体:**
  199. {
  200. "start": 1356998400,
  201. "end": 1356998460,
  202. "queries": [
  203. {
  204. "aggregator": "sum",
  205. "metric": "sys.cpu.0",
  206. "rate": "true",
  207. "filters": [
  208. {
  209. "type": "wildcard",
  210. "tagk": "host",
  211. "filter": "*",
  212. "groupBy": true
  213. },
  214. {
  215. "type": "literal_or",
  216. "tagk": "dc",
  217. "filter": "lga|lga1|lga2",
  218. "groupBy": false
  219. }
  220. ]
  221. }
  222. ]
  223. }
  224. ### 查询结果说明
  225. 查询成功的 HTTP 响应码为 200,响应内容为 JSON 格式数据。说明如下:
  226. 名称|描述
  227. -|-
  228. metric|指标名
  229. tags|tagv 未做聚合的 tag
  230. aggregateTags|tagv 做了聚合的 tag
  231. dps|数据点对
  232. **响应结果示例:**
  233. [
  234. {
  235. "metric": "tsd.hbase.puts",
  236. "tags": {"appName": "hitsdb"},
  237. "aggregateTags": [
  238. "host"
  239. ],
  240. "dps": {
  241. "1365966001": 25595461080,
  242. "1365966061": 25595542522,
  243. "1365966062": 25595543979,
  244. "1365973801": 25717417859
  245. }
  246. }
  247. ]
  248. ## 查询 Hint 化说明
  249. ### 场景说明
  250. 该特性主要是提高查询速度。假设某一个 tags A 命中的时间线明显大于其他的 tags B 命中的时间线,则需要舍弃,避免捞取 tags A 的大量时间线之后,被 tagsB 小规模时间线交集后,结果集等于 tagsB
  251. ### 格式说明
  252. - 当前版本只支持 tagk 级别的查询索引限制
  253. - 其中,`0` 表示不使用对应 tagk 的索引,反之 `1` 表示使用对应 tagk 的索引
  254. ### 查询示例
  255. #### 包含 filter 的查询示例
  256. ##### 子查询级别
  257. ```json
  258. {
  259. "start": 1346846400,
  260. "end": 1346846400,
  261. "queries": [
  262. {
  263. "aggregator": "none",
  264. "metric": "sys.cpu.nice",
  265. "tags": {
  266. "dc": "lga",
  267. "host": "web01"
  268. },
  269. "hint": {
  270. "tagk": {
  271. "dc": 1
  272. }
  273. }
  274. }
  275. ]
  276. }
整体查询级别
  1. {
  2. "start": 1346846400,
  3. "end": 1346846400,
  4. "queries": [
  5. {
  6. "aggregator": "none",
  7. "metric": "sys.cpu.nice",
  8. "tags": {
  9. "dc": "lga",
  10. "host": "web01"
  11. }
  12. }
  13. ],
  14. "hint": {
  15. "tagk": {
  16. "dc": 1
  17. }
  18. }
  19. }
不可同时指定 0 和 1
  1. {
  2. "start": 1346846400,
  3. "end": 1346846400,
  4. "queries": [
  5. {
  6. "aggregator": "none",
  7. "metric": "sys.cpu.nice",
  8. "tags": {
  9. "dc": "lga",
  10. "host": "web01"
  11. }
  12. }
  13. ],
  14. "hint": {
  15. "tagk": {
  16. "dc": 1,
  17. "host": 0
  18. }
  19. }
  20. }
  1. {
  2. "error": {
  3. "code": 400,
  4. "message": "The value of hint should only be 0 or 1, and there should not be both 0 and 1",
  5. "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=[])"
  6. }
  7. }
不可指定除了 0 和 1 之外的值
  1. {
  2. "start": 1346846400,
  3. "end": 1346846400,
  4. "queries": [
  5. {
  6. "aggregator": "none",
  7. "metric": "sys.cpu.nice",
  8. "tags": {
  9. "dc": "lga",
  10. "host": "web01"
  11. }
  12. }
  13. ],
  14. "hint": {
  15. "tagk": {
  16. "dc": 100
  17. }
  18. }
  19. }
  1. {
  2. "error": {
  3. "code": 400,
  4. "message": "The value of hint can only be 0 or 1, and it is detected that '100' is passed in",
  5. "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=[])"
  6. }
  7. }