單值查詢數據
本文介紹單值查詢數據信息。
請求路徑和方法
請求路徑：/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 | 否 | 根據提供的條件在掃描原始數據點時進行過濾，支持”>”, “<”, “=”,”<=”, “>=”, “!=”。 說明 它與 | 無 | >=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
*.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, 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 ] } } ]