:単一値のクエリ

タイムスタンプの単位

TSDB は数値に基づいてタイムスタンプの単位を判別します。

これらのルールは、/api/put（書き込み）および /api/query（クエリ）の両方に適用されます。

単一時点のデータポイントをクエリするには、start および end を同一の値に設定します（例： 1356998400）。

サブクエリパラメーター

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

1 回のリクエストでサポートされるサブクエリの最大数は 200 です。

tags および filters の両方が指定されている場合、JSON 内で後に出たパラメーターが有効になります。

リクエスト例

POST /api/query

{
  "start": 1356998400,
  "end": 1356998460,
  "queries": [
    {
      "aggregator": "sum",
      "metric": "sys.cpu.0",
      "rate": "true",
      "tags": {
        "host": "*",
        "dc": "lga"
      }
    }
  ]
}

deltaOptions

サブクエリ内で deltaOptions を構成することで、デルタの計算方法を制御できます。

例

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

フィールド

`interval`

5 や 60 などの数値です。0all を使用すると、範囲内のすべてのデータポイントが単一の値に集約されます。

`units`

デフォルトでは、タイムスタンプはモジュロ切り捨てにより整合されます：整合済みタイムスタンプ = データタイムスタンプ − (データタイムスタンプ % 時間間隔)。

カレンダー間隔（たとえば 00:00 から翌日の 00:00 まで）で整合させるには、単位の末尾に c を追加します：1dc。

`aggregator`

rfirst、rlast、rmin、および rmax 演算子は、同じダウンサンプリング式内でフィルポリシーと併用できません。

フィルポリシー

フィルポリシーは、ダウンサンプリング結果における欠損値の埋め方を定義します。タイムウィンドウ内にデータが存在しない場合、TSDB はフィルポリシーを適用して値を生成します。

固定フィルポリシー

欠損値を固定数で埋めるには、以下のフォーマットを使用します。

<interval><units>-<aggregator>-fixed#<number>

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

ダウンサンプリングの例

1m-avg、1h-sum-zero、1h-sum-near

補間

複数のタイムラインをマージする場合、特定のタイムスタンプで値が欠落しているタイムラインには、フィルポリシーが指定されておらず、かつ他のタイムラインの少なくとも 1 つがそのタイムスタンプで値を持つ場合に限り、補間値が割り当てられます。

たとえば、{"downsample": "10s-avg", "aggregator": "sum"} を使用して 2 つのタイムラインをマージする場合：

• タイムライン 1 には t+0、t+10、t+20、t+30 に値があります。

• タイムライン 2 には t+0、t+20、t+30 に値があります。

集約前に、TSDB はタイムライン 2 の t+10 に対して補間値を計算します。補間方法は集約関数によって異なります。

フィルターの種類

フィルターなしの例

{
  "start": 1356998400,
  "end": 1356998460,
  "queries": [
    {
      "aggregator": "sum",
      "metric": "sys.cpu.0",
      "rate": "true",
      "tags": {
        "host": "*",
        "dc": "lga"
      }
    }
  ]
}

フィルターありの例

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

エラー事例

0 と 1 の混在

以下のリクエストは、dc が 1 で host が 0 であるためエラーになります。

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

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": "ヒントの値は 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=[])"
  }
}

異常検出の出力

dps 内の各値は、以下の形式の配列です。

[srcValue, upperValue, lowerValue, predictValue, isAbnormal]

出力例

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