本文介紹單值查詢資料資訊。
請求路徑和方法
請求路徑：/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 ] } } ]