：多值資料查詢

多值模型資料查詢 mquery

請求路徑和方法

請求內容

時間戳記說明

時間戳記的單位可以是秒或者毫秒。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/mput）和查詢資料（/api/query & /api/mquery）兩個介面。

單時間點資料查詢

TSDB支援單時間點資料查詢。您可以將開始時間和結束時間設定為相同的數值。

例如："start":1356998400，"end":1356998400。

子查詢 JSON 格式

域查詢資訊 JSON 格式

查詢樣本

請求：POST/api/mquery請求體

{
    "start" : 1346846400,
    "end" :   1346846411,
    "msResolution" : true,
    "queries" : [
        {
            "metric" : "wind",
            "fields" : [
                {
                    "field" : "speed",
                    "aggregator" : "sum",
                    "downsample" : "2s-last",
                      "alias" : "speed_sum"
                },
                {
                    "field" : "*",
                    "aggregator" : "sum",
                    "downsample" : "2s-count",
                    "where":"speed>10"
                }
            ]
        }
    ]
}

資料分頁查詢（Limit 和 Offset）說明

Limit：子查詢每條時間序列返回資料點的最大數目。預設值是0，代表不限制返回點數量。

Offset：子查詢每條時間序列返回資料點的位移量。預設值也是0，代表不位移返回的資料點。

樣本

返回第1001到1500的資料點，則limit設為500，offset設為1000。

{
    "start" : 1346846400,
    "end"  :  1346846411,
    "msResolution" : true,
    "queries" : [
        {
            "metric" : "wind",
            "fields" : [
                {
                    "field" : "*",
                    "aggregator" : "sum",
                    "downsample" : "2s-count"
                }
            ],
            "filters" : [
                {
                    "filter" : "IOTE_8859_0005|IOTE_8859_0004",
                    "tagk" : "sensor",
                    "type" : "literal_or"
                }
            ],
            "limit" : 500,
            "offset" : 1000
        }
    ]
}

值過濾（dpValue） 說明

根據使用者佈建的數值限制條件，過濾最終的返回資料點。支援 “>”、“<”、 “=”、 “<=”、 “>=”、 “!=”。

樣本

{
    "start" : 1346846400,
    "end" :   1346846411,
    "msResolution" : true,
    "queries" : [
        {
            "metric" : "wind",
            "fields" : [
                {
                    "field" : "level",
                    "aggregator" : "avg",
                    "downsample" : "2s-avg",
                    "dpValue" : ">=8.0"
                }
            ],
            "filters" : [
                {
                    "filter" : "IOTE_8859_0005|IOTE_8859_0004",
                    "tagk" : "sensor",
                    "type" : "literal_or"
                }
            ]
        }
    ]
}

    {
       "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代表年。

  說明

  • 預設按照時間戳記模數對齊，即“對齊時間戳記=資料時間戳記-（資料時間戳記 % interval）”。

  • 支援基於日曆時間間隔的降採樣。要使用日曆界限，您需要在時間單位units後添加一個c。例如，1dc代表從當日零點到次日零點之間的 24 小時。

• aggregator：降採樣使用的運算元及其說明如下表所示。

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

彙總（Aggregate）說明

在降採樣後會得到多條時間軸的值，並且這些時間軸的時間戳記是對齊的，而彙總就是把多條時間軸的值按各個對齊時刻彙總為一條時間軸的結果（注意：如果只有一條時間軸，則不進行彙總）。彙總時必須要求每條時間軸在對應時刻都有值，如果某條時間軸在某個時刻沒有值，則會進行插值，插值描述如下。

插值

如果某條時間軸某個精度區間沒有值且沒有使用fill policy進行填值，而待彙總的其他時間軸中有一條時間軸在此精度區間有值，則會對本時間軸的這個缺值精度區間進行插值。

例如：降採樣以及彙總條件為{"downsample": "10s-avg", "aggregator": "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做分組，相同的tagv做彙總。

  • tagk = tagv1|tagv2：分別對tagk下面的tagv1和tagv2資料做彙總。

• 使用JSON格式指定filter：

Filter 類型說明

查詢樣本

包含 filter 的查詢樣本

請求體：

{
    "start" : 1346846400,
    "end" :   1346846411,
    "msResolution" : true,
    "queries" : [
        {
            "metric" : "wind",
            "fields" : [
                {
                    "field" : "speed",
                    "aggregator" : "none",
                    "alias" : "column_speed"
                },
                {
                      "field" : "*",
                    "aggregator" : "none",
                    "alias" : "column_"
                }
            ],
            "filters" : [
                {
                    "filter" : "IOTE_8859_0005|IOTE_8859_0004",
                    "tagk" : "sensor",
                    "type" : "literal_or"
                }
            ]
        }
    ]
}

查詢結果說明

查詢成功的HTTP響應碼為200，響應內容為JSON格式資料。說明如下：

響應結果樣本：

• Aggregator : None情境樣本

[
   {
      "metric":"wind",
      "columns":[
         "timestamp",
         "column_speed",
         "column_description",
         "column_direction",
         "column_level",
         "column_speed"
      ],
      "tags":{
         "city":"hangzhou",
         "country":"china",
         "province":"zhejiang",
         "sensor":"IOTE_8859_0005"
      },
      "aggregatedTags":[],
      "values":[
         [ 1346846406000, null, "Fresh breeze", "East", 0.5, null ],
         [ 1346846407000, null, "Fresh breeze", "South", 1.5, null ]
   },
   {
      "metric":"wind",
      "columns":[
         "timestamp",
         "column_speed",
         "column_description",
         "column_direction",
         "column_level",
         "column_speed"
      ],
      "tags":{
         "city":"hangzhou",
         "country":"china",
         "province":"zhejiang",
         "sensor":"IOTE_8859_0004"
      },
      "aggregatedTags":[],
      "values":[
         [ 1346846400000, 40.4, "Fresh breeze", "East", 0.4, 40.4 ],
         [ 1346846401000, 41.4, "Fresh breeze", "South", 1.4, 41.4 ],
         [ 1346846402000, 42.4, "Fresh breeze", "West", 2.4, 42.4 ],
         [ 1346846403000, 43.4, "Fresh breeze", "North", 3.4,43.4 ]
   }
]

• Aggregator：Avg 的情境樣本（查看杭州市所有sensor監控的平均風速和平均風等級）

[
  {
    "metric": "wind",
    "columns": [
      "timestamp",
      "avg_level",
      "avg_speed"
    ],
    "tags": {
      "city": "hangzhou"
    },
    "aggregatedTags": [
      "country",
      "province",
      "sensor"
    ],
    "values": [
      [1346846400000, 0.25, 40.25],
      [1346846401000, 1.25, 41.25],
      [1346846402000, 2.5, 42.5],
      [1346846411000, 5.5, null]
    ]
  }
]

查詢 Hint 化說明

情境說明

該特性主要是提高查詢速度。假設某一個tags A命中的時間軸明顯大於其他的tags B命中的時間軸，則需要捨棄，避免撈取tags A的大量時間軸之後，被tags B小規模時間軸交集後，結果集等於tags B。

格式說明

• 目前的版本只支援tagk層級的查詢索引限制（hint下的tagk是固定寫法）。

• 其中，0表示不使用對應tagk的索引，反之1表示使用對應tagk的索引。

版本說明

從v2.6.1版本開始支援hint特性。

查詢樣本

子查詢層級

{
  "queries": [
    {
      "metric": "demo.mf",
      "tags": {
        "sensor": "IOTE_8859_0001",
        "city": "hangzhou",
        "province": "zhejiang",
        "country": "china"
      },
      "fields": [
        "speed"
      ],
      "hint": {
        "tagk": {
          "dc": 1
        }
      }
    }
  ]
}

整體查詢層級

{
  "queries": [
    {
      "metric": "demo.mf",
      "tags": {
        "sensor": "IOTE_8859_0001",
        "city": "hangzhou",
        "province": "zhejiang",
        "country": "china"
      },
      "fields": [
        "speed"
      ]
    }
  ],
  "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=[])"
    }
}