:マルチ値データのクエリ

リクエスト

エンドポイント

リクエスト本文のパラメーター

サブクエリのパラメーター

queries 配列内の各オブジェクトは、以下のパラメーターをサポートします：

フィールドクエリのパラメーター

fields 配列内の各オブジェクトは、以下のパラメーターをサポートします：

1 つのクエリで、すべてのサブクエリを含めたフィールド値の合計は最大 200 個までです。カウント方法：すべてのサブクエリ内の field 値の数を、すべての fields 配列で合計します。

タイムスタンプの単位

TSDB は数値の範囲に基づいてタイムスタンプの単位を決定します：

これらのルールは /api/put、/api/mput、/api/query、および /api/mquery に適用されます。

単一時点のデータをクエリするには、start および end を同じ値に設定します。例："start": 1356998400, "end": 1356998400。

サンプルリクエスト

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"
        }
      ]
    }
  ]
}

ダウンサンプリング

ダウンサンプリングは、固定時間間隔でデータを集約し、返されるデータポイント数を削減します。1 秒単位の粒度が不要な長期間のクエリ時に使用します。

式の形式

<間隔><単位>-<集約関数>[-塗りつぶしポリシー]

`間隔`： 5 や 60 などの数値です。0all を使用すると、範囲内のすべてのデータポイントを 1 つの値に集約します。

`単位`：

c を追加すると、カレンダーによる配置（例： 1dc は当日 00:00 からの 24 時間を表します）が有効になります。c を指定しない場合、タイムスタンプの配置は次の式で行われます：配置済みタイムスタンプ = データタイムスタンプ − (データタイムスタンプ % 間隔)。

`集約関数` の選択肢：

rfirst、rlast、rmin、および rmax 演算子は、塗りつぶしポリシーとともに使用できません。

時間ウィンドウの拡張

downsample を指定すると、TSDB は自動的にクエリ範囲を両側に 1 つの間隔分拡張します。たとえば、範囲が [1346846401, 1346846499] で間隔が 5m の場合、実際のクエリ範囲は [1346846101, 1346846799] になります。

フィル ポリシー

タイムバケットにデータポイントがない場合、塗りつぶしポリシーにより、そのバケットに対して報告される値が決定されます。

固定塗りつぶしポリシー

フォーマットに固定値を # を使用して追加します：

<間隔><単位>-<集約関数>-fixed#<数値>

固定値は正または負の値を指定できます。例：1h-sum-fixed#6、1h-avg-fixed#-8。

ダウンサンプリングの例

有効なダウンサンプリング式の例： 1m-avg、1h-sum-zero、1h-sum-near。

集約関数

ダウンサンプリング後、複数のタイムラインが配置済みタイムスタンプを共有することがあります。aggregator は、各タイムスタンプにおける値を集約することで、それらのタイムラインを 1 つにマージします。タイムラインが 1 つのみの場合、集約は実行されません。

補間

複数のタイムラインを集約する場合、あるタイムラインが配置済みタイムスタンプに値を持たず、他のタイムラインが持つ場合、TSDB は欠落しているタイムラインに対して補間値を計算します。これは塗りつぶしポリシーが設定されていない場合にのみ適用されます。

補間方法は集約関数によって異なります：

デルタ演算子

delta が true に設定されている場合、dps の各キーと値のペア内の value は、計算されたデルタ (Vt − Vt-1) で置き換えられます。

`deltaOptions` のパラメーター

例

{
  "start": 1346046400,
  "end": 1347056500,
  "queries": [
    {
      "metric": "sys.cpu.0",
      "aggregator": "none",
      "downsample": "5s-avg",
      "delta": true,
      "deltaOptions": {
        "counter": true,
        "counterMax": 100
      },
      "dpValue": ">=50",
      "tags": {
        "host": "localhost",
        "appName": "hitsdb"
      }
    }
  ]
}

limit および offset を使用したページ分割

limit および offset を使用して、複数のタイムラインにわたる結果をページ分割します。

• limit：ページあたりのタイムラインごとの最大データポイント数です。0 は制限なし（デフォルト）を意味します。

• offset：タイムラインごとにスキップするデータポイント数です。

例： 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
    }
  ]
}

フィルター

フィルターは、タグ値に基づいてクエリに含めるタイムラインを選択します。filters パラメーターは tags と競合します — JSON 内で両方が出現した場合、後に出た方の設定が有効になります。

フィルター・オブジェクトのパラメーター

フィルターの種類

また、タグのショートハンドを使用してフィルターを指定することもできます：

• tagk = *：そのキーのすべてのタグ値をグループ化し、個別の値ごとに集約します。

• tagk = tagv1|tagv2： tagv1 の値をまとめてグループ化し、tagv2 の値をまとめてグループ化します。

フィルターを使用した例

{
  "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` に設定した場合

一致したタイムラインごとに 1 つの結果オブジェクトを返します（センサー間での集約は行いません）：

[
  {
    "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` に設定した場合

都市内のすべてのセンサーにわたる平均風速および平均レベルを返します：

[
  {
    "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]
    ]
  }
]

クエリ ヒント

クエリヒントワードは、TSDB に対してタイムライン解決時にどのタグインデックスを使用（またはスキップ）するかを指示し、あるタグセットによってターゲットとなるタイムラインの集合が、他のタグセットの既知のサブセットである場合に応答時間を短縮します。

フォーマット

hint.tagk の下にタグキー名を指定し、値として 0（インデックスをスキップ）または 1（インデックスを使用）を設定します。1 つのヒントワード内では、すべての値が 0 またはすべてが 1 である必要があります — 混在するとエラーが発生します。

サブクエリにスコープを限定したヒントワード

{
  "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": "ヒントワードの値は 0 または 1 のみであり、0 と 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=[])"
  }
}

エラー：無効なヒントワードの値

{
  "start": 1346846400,
  "end": 1346846400,
  "queries": [
    {
      "aggregator": "none",
      "metric": "sys.cpu.nice",
      "tags": {
        "dc": "lga",
        "host": "web01"
      }
    }
  ],
  "hint": {
    "tagk": {
      "dc": 100
    }
  }
}

返されるレスポンス：

{
  "error": {
    "code": 400,
    "message": "ヒントワードの値は 0 または 1 のみであり、'100' が渡されたことが検出されました",
    "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=[])"
  }
}