多変量データポイントのクエリ - - Alibaba Cloud ドキュメントセンター

このトピックでは、多変量データポイントをクエリする方法について説明します。

mquery を使用して多変量データポイントをクエリする

リクエストパスとメソッド

リクエストパス	リクエストメソッド	説明
/api/mquery	POST	データをクエリします。

重要

単変量データポイントの挿入に使用するリクエストパスは、多変量データポイントの挿入に使用するリクエストパスとは異なります。単変量データポイントを書き込むには、/api/put オペレーションを呼び出します。多変量データポイントをクエリするには、/api/mquery オペレーションを呼び出します。単変量データポイントをクエリするには、/api/query オペレーションを呼び出します。

データポイントのパラメーター

パラメーター	タイプ	必須	説明	デフォルト値	例
start	Long	はい	開始時刻。単位：秒またはミリ秒。単位を決定するルールについては、「タイムスタンプ単位」セクションを参照してください。	なし	1499158925
end	Long	いいえ	終了時刻。単位：秒またはミリ秒。単位を決定するルールについては、「タイムスタンプ単位」セクションを参照してください。デフォルト値は、Time Series Database（TSDB）サーバーの現在の時刻です。	現在の時刻	1499162916
queries	Array	はい	サブクエリ配列。	なし	詳細については、「JSON 形式のサブクエリのパラメーター」セクションをご参照ください。
msResolution	boolean	いいえ	サブクエリ配列。	false	このパラメーターは、クエリするデータポイントのタイムスタンプが秒単位で測定されている場合にのみ有効になります。値を true に設定すると、クエリ結果のタイムスタンプの単位はミリ秒になります。それ以外の場合、元のタイムスタンプ単位が保持されます。クエリするデータポイントのタイムスタンプがミリ秒の場合、このパラメーターの値が true か false かに関係なく、クエリ結果のタイムスタンプ単位はミリ秒になります。
hint	Map	いいえ	クエリヒント。	なし	詳細については、「パラメーター：hint」セクションをご参照ください。

タイムスタンプ単位

タイムスタンプは、秒またはミリ秒単位で測定できます。TSDB は、タイムスタンプの数値に基づいて、次のルールを使用してタイムスタンプの単位を決定します。

タイムスタンプが [4284768,9999999999] の範囲内にある場合、TSDB はタイムスタンプが秒単位で測定されていると判断します。この場合、対応する日付と時刻の範囲は [1970-02-20 00:59:28, 2286-11-21 01:46:39] です。
タイムスタンプが [10000000000,9999999999999] の範囲内にある場合、TSDB はタイムスタンプがミリ秒単位であると判断します。この場合、対応する日付と時刻の範囲は [1970-04-27 01:46:40.000,2286-11-21 01:46:39.999] です。
タイムスタンプが (-∞,4284768) または (9999999999999,+∞) の範囲内にある場合、TSDB はタイムスタンプが無効であると判断します。
説明
このセクションでは、タイムスタンプの単位を決定するルールについて説明します。これらのルールは、次の API オペレーションに適用されます。/api/put、/api/mput、/api/query、および /api/mquery。/api/put および /api/mput はデータの書き込みに使用されます。/api/query および /api/mquery はデータのクエリに使用されます。

特定の時点のデータポイントをクエリする

TSDB では、特定の時点のデータポイントをクエリできます。特定の時点のデータポイントをクエリするには、開始時刻と終了時刻を同じ値に設定します。

たとえば、start パラメーターと end パラメーターを 1356998400 に設定できます。

JSON 形式のサブクエリのパラメーター

パラメーター	タイプ	必須	説明	デフォルト値	例
metric	String	はい	メトリック名。	なし	wind
fields	List	はい	返すフィールド。	なし	-
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	いいえ	生のデータポイントのスキャンに使用するフィルタリング条件。サポートされている演算子は、>、<、=、<=、>=、および != です。説明注：preDpValue は `dpValue` とは異なります。preDpValue は、スキャン中に保存されるデータポイントをフィルタリングするために使用されます。dpValue は、クエリ後に計算された結果をフィルタリングするために使用されます。preDpValue を使用すると、フィルタリング条件を満たさないデータポイントはクエリと計算に含まれません。	なし	>=1000
downsample	String	いいえ	ダウンサンプリング設定。	なし	60m-avg
tags	Map	いいえ	返すデータポイントのタグ。このパラメーターは、filters パラメーターと競合します。	なし	-
filters	List	いいえ	フィルタリング条件を指定します。このパラメーターは、tags パラメーターと競合します。	なし	-
hint	Map	いいえ	クエリヒント。	なし	詳細については、「パラメーター：hint」セクションをご参照ください。

説明

各クエリで field パラメーターに最大 200 個の値を指定できます。次の例で詳細を説明します。
この例では、クエリに 3 つのサブクエリが含まれています。最初のサブクエリでは、field パラメーターに 3 つの値を指定します。2 番目のサブクエリでは、field パラメーターに 2 つの値を指定します。3 番目のサブクエリでは、field パラメーターに 6 つの値を指定します。したがって、クエリ内の field パラメーターの値の総数は 11 になります。11 は、totalFields パラメーターの値の数です。クエリを実行する前に、クエリ内の totalFields パラメーターの値の数が 200 を超えていないことを確認してください。
tags パラメーターと filters パラメーターの両方を指定した場合、JSON 形式のデータで後方に指定したパラメーターが有効になります。

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

パラメーター	タイプ	必須	説明	デフォルト値	例
aggregator	String	はい	集計関数。詳細については、「パラメーター：aggregator」セクションをご参照ください。	なし	sum
field	String	はい	フィールドの名前。アスタリスク (*) を使用して、メトリックのすべてのフィールドをクエリできます。	なし	-
alias	String	いいえ	返すフィールドのエイリアス。	なし	-
downsample	String	いいえ	ダウンサンプリング設定。	なし	60m-avg
rate	Boolean	いいえ	指定されたメトリックの値間の増加率を計算するかどうかを指定します。増加率は、次の式に基づいて計算されます。増加率 = (Vt - Vt-1)/(t1 - t-1)。	false	true
dpValue	String	いいえ	返されるデータポイントをフィルタリングするためのフィルタリング条件。サポートされている演算子は、>、<、=、<=、>=、および != です。	なし	>=1000
where	String	いいえ	field パラメーターがワイルドカード文字 (*) に設定されている場合、where パラメーターを使用して、クエリ後に結果が計算されるときにフィルタリングされるフィールドを指定できます。where パラメーターは、`dpValue` と同じように機能します。2 つのパラメーターは、クエリ後に計算された結果をフィルタリングします。	なし	f1>=100

説明

limit、dpValue、downsample、tags、および filters パラメーターの詳細については、以下の説明をご参照ください。

リクエストの例

リクエスト本文：POST/api/query

{
    "start" : 1346846400,
    "end" :   1346846411,
    "msResolution" : true,
    "queries" : [
        {
            "metric" : "wind",
            "fields" : [
                {
                    "field" : "speed", // フィールド speed
                    "aggregator" : "sum", // 集計関数 sum
                    "downsample" : "2s-last", // ダウンサンプリング設定 2s-last
                      "alias" : "speed_sum" // エイリアス speed_sum
                },
                {
                    "field" : "*", // 全てのフィールド
                    "aggregator" : "sum", // 集計関数 sum
                    "downsample" : "2s-count", // ダウンサンプリング設定 2s-count
                    "where":"speed>10" // speed が 10 より大きいデータをフィルタリング
                }
            ]
        }
    ]
}

limit パラメーターと offset パラメーターを使用する

limit パラメーターは、サブクエリごとに各タイムラインで返されるデータポイントの最大数を指定します。 limit パラメーターのデフォルト値は 0 です。デフォルト値 0 は、返されるデータポイントの数に制限がないことを指定します。

offset パラメーターは、サブクエリで各タイムラインにおいてスキップするデータポイントの数を指定します。 offset パラメーターのデフォルト値は 0 です。デフォルト値 0 は、データポイントがスキップされないことを指定します。

重要

limit パラメーターまたは offset パラメーターを負の数に設定することはできません。
limit パラメーターと offset パラメーターは、ページクエリで返す多変量データポイントに対して機能します。単一のフィールドクエリには、2 つのパラメーターを使用できません。

例

ランキングが 1001 位から 1500 位までのデータポイントを取得する場合、limit パラメーターを 500 に、offset パラメーターを 1000 に設定します。

{
    "start" : 1346846400,
    "end"  :  1346846411,
    "msResolution" : true,
    "queries" : [
        {
            "metric" : "wind",
            "fields" : [
                {
                    "field" : "*", // 全てのフィールド
                    "aggregator" : "sum", // 集計関数 sum
                    "downsample" : "2s-count" // ダウンサンプリング設定 2s-count
                }
            ],
            "filters" : [
                {
                    "filter" : "IOTE_8859_0005|IOTE_8859_0004", // フィルター IOTE_8859_0005 または IOTE_8859_0004
                    "tagk" : "sensor", // タグキー sensor
                    "type" : "literal_or" // フィルタータイプ literal_or
                }
            ],
            "limit" : 500, // 最大 500 件のデータポイントを返す
            "offset" : 1000 // 先頭の 1000 件のデータポイントをスキップする
        }
    ]
}

パラメーター：dpValue

dpValue パラメーターは、データ値の制限を指定します。このパラメーターを指定して、返されるデータポイントをフィルタリングできます。有効な値は、>、<、=、<=、>=、および != です。

重要

サブクエリで dpValue を使用して複数のフィールドのデータをクエリする場合、各サブクエリの dpValue は個別に機能します。各サブクエリの dpValue は、フィールド全体で同じように機能するわけではありません。

このパラメーターが文字列に設定されている場合、文字列には = と != の演算子のみを含めることができます。

例

{
    "start" : 1346846400,
    "end" :   1346846411,
    "msResolution" : true,
    "queries" : [
        {
            "metric" : "wind",
            "fields" : [
                {
                    "field" : "level", // フィールド level
                    "aggregator" : "avg", // 集計関数 avg
                    "downsample" : "2s-avg", // ダウンサンプリング設定 2s-avg
                    "dpValue" : ">=8.0" // 8.0 以上のデータポイントをフィルタリング
                }
            ],
            "filters" : [
                {
                    "filter" : "IOTE_8859_0005|IOTE_8859_0004", // フィルター IOTE_8859_0005 または IOTE_8859_0004
                    "tagk" : "sensor", // タグキー sensor
                    "type" : "literal_or" // フィルタータイプ literal_or
                }
            ]
        }
    ]
}

演算子：delta

サブクエリで delta 演算子を指定すると、TSDB によって返される dps データポイントの key-value ペアの value は、計算された差分になります。

重要

delta パラメーターが指定されていない場合に返される dps データポイントに nkey-value ペアが含まれている場合、差分が計算された後に返される dps データポイントには、n-1key-value ペアのみが含まれます。最初の key-value ペアは、このペアの差分を計算できないため使用されません。delta 演算子は、downsampling 後の値にも適用されます。

delta 演算子を指定した後、サブクエリで deltaOptions を設定して、差分の計算方法をさらに制御できます。次の表に、deltaOptions に使用できるパラメーターを示します。

パラメーター	タイプ	必須	説明	デフォルト値	例
counter	Boolean	いいえ	このマーカービットを指定すると、差分の計算に想定されるメトリック値を、単調に増加または減少する累積値と見なすことができます。累積値は、カウンターの値に似ています。サーバーはメトリック値をチェックしません。	false	true
counterMax	Integer	いいえ	counter パラメーターが true に設定されている場合、counterMax パラメーターは差分のしきい値を指定します。差分の絶対値がしきい値を超えると、差分は異常です。counterMax パラメーターの値を指定しない場合、差分にしきい値はありません。	なし	100
dropReset	Boolean	いいえ	このマーカービットは、`counterMax` と一緒に使用する必要があります。`counterMax` パラメーターが指定されていて、計算された差分が異常な場合、`dropReset` パラメーターを使用して、異常な差分を破棄するかどうかを指定できます。dropReset パラメーターが true に設定されている場合、例外の原因となる差分は破棄されます。このパラメーターが false に設定されているか、デフォルトで false の場合、例外の原因となる差分は 0 にリセットされます。	false	true

例

    {
       "start":1346046400, // 開始時刻
       "end":1347056500, // 終了時刻
       "queries":[
          {
             "aggregator":"none", // 集計なし
             "downsample":"5s-avg", // ダウンサンプリング設定 5s-avg
             "delta":true, // 差分を計算する
             "deltaOptions":{ // 差分オプション
                 "counter":true, // カウンターとして扱う
                 "counterMax":100 // カウンターの最大値
             }
             "metric":"sys.cpu.0", // メトリック名
             "dpValue":">=50", // 50 以上のデータポイントをフィルタリング
             "tags":{ // タグ
                "host":"localhost", // タグキー host, タグ値 localhost
                "appName":"hitsdb" // タグキー appName, タグ値 hitsdb
             }
          }
       ]
    }

パラメーター：downsample

このパラメーターは、長い時間範囲で生成されたデータをクエリし、指定された時間間隔に基づいてデータを集計する必要がある場合に使用します。タイムラインは、ダウンサンプリング用に指定された時間間隔に基づいて複数の時間範囲に分割されます。返される各タイムスタンプは、各時間範囲の開始を示します。次のサンプルコードは、クエリの形式の例を示しています。

<interval><units>-<aggregator>[-fill policy]

重要

downsample パラメーターを指定した後、データ集計用に指定された interval と同じ長さの時間ウィンドウが、指定された時間範囲の開始と終了に自動的に追加されます。たとえば、指定されたタイムスタンプ範囲が [1346846401,1346846499] で、指定された interval が 5 分の場合、クエリの実際のタイムスタンプ範囲は [1346846101,1346846799] です。

次のセクションでは、クエリで使用されるパラメーターについて説明します。

interval：5 や 60 などの数値を指定します。値 0all は、時間範囲内のデータポイントが単一の値に集計されることを指定します。
units：単位。s は秒を表します。m は分を表します。h は時間を表します。d は日を表します。n は月を表します。y は年を表します。
説明
- デフォルトでは、タイムスタンプを揃えるために、剰余演算と切り捨て演算が実行されます。タイムスタンプは、次の式を使用して揃えられます。揃えられたタイムスタンプ = データタイムスタンプ - (データタイムスタンプ % 時間間隔)。
- カレンダ時間間隔に基づいてデータをダウンサンプリングできます。カレンダ時間間隔を使用するには、units パラメーターの値の最後に c を追加します。たとえば、1dc は、現在の日の 00:00 から次の日の 00:00 までの 24 時間の期間を指定します。
aggregator：集計設定。次の表に、ダウンサンプリングに使用される演算子を示します。

演算子	説明
avg	平均値を返します。
count	データポイントの数を返します。
first	最初の値を返します。
last	最後の値を返します。
min	最小値を返します。
max	最大値を返します。
sum	値の合計を返します。
zimsum	値の合計を返します。
rfirst	`first` 演算子によって返されるのと同じデータポイントを返します。返されるタイムスタンプは、揃えられたタイムスタンプではなく元のタイムスタンプです。データポイントのタイムスタンプは、データがダウンサンプリングされた後に揃えられます。
rlast	`last` 演算子によって返されるのと同じデータポイントを返します。返されるタイムスタンプは、揃えられたタイムスタンプではなく元のタイムスタンプです。データポイントのタイムスタンプは、データがダウンサンプリングされた後に揃えられます。
rmin	`min` 演算子によって返されるのと同じデータポイントを返します。返されるタイムスタンプは、揃えられたタイムスタンプではなく元のタイムスタンプです。データポイントのタイムスタンプは、データがダウンサンプリングされた後に揃えられます。
rmax	`max` 演算子によって返されるのと同じデータポイントを返します。返されるタイムスタンプは、揃えられたタイムスタンプではなく元のタイムスタンプです。データポイントのタイムスタンプは、データがダウンサンプリングされた後に揃えられます。

説明

ダウンサンプリング式で aggregator を rfirst、rlast、rmin、または rmax 演算子に設定した場合、ダウンサンプリング式で fill policy パラメーターを設定することはできません。

入力ポリシー

fill policy パラメーターを指定して、欠損値を事前定義された値で入力する方法を決定できます。ダウンサンプリング中、すべてのタイムラインは指定された時間間隔に基づいて分割され、各時間範囲のデータポイントが集計されます。ダウンサンプリング結果の時間範囲に値が存在しない場合、fill policy を指定して、欠損値を事前定義された値で入力できます。例を使用して、入力ポリシーを説明します。この例では、ダウンサンプリング後のタイムラインのタイムスタンプは t+0、t+20、および t+30 です。fill policy を指定しない場合、3 つの値のみが報告されます。fill policy を null に設定すると、4 つの値が報告されます。時点 t+10 の欠損値は、null で入力されます。次の表に、fill policies と入力される値を示します。

入力ポリシー	値
none	値は入力されません。これはデフォルト値です。
nan	NaN
null	null
zero	0
linear	線形補間に基づいて計算された値。
previous	前の値。
near	隣接する値。
after	次の値。
fixed	ユーザー指定の固定値。詳細については、このトピックの「固定入力ポリシー」セクションの説明をご参照ください。

固定入力ポリシー

欠損値を固定値で入力するには、番号記号（#）の最後に固定値を追加します。固定値は、正の数または負の数として指定できます。次のサンプルコードは、有効な形式の例を示しています。

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

例: 1h-sum-fixed#6 と 1h-avg-fixed#-8

ダウンサンプリングの例

3 つのダウンサンプリングの例は、1m-avg、1h-sum-zero、および 1h-sum-near です。

重要

フィールドクエリでは、downsample パラメーターはオプションです。このパラメーターを null に設定するか、("") 形式で空のままにすることができます。{"downsample": null} または {"downsample": ""}。この場合、データはダウンサンプリングされません。フィールドクエリで downsample パラメーターを指定する場合は、同じサブクエリに属する他のフィールドクエリにもこのパラメーターを指定します。同じサブクエリに属するすべてのフィールドクエリで、フィールドデータを downsample するために同じインターバル時間を指定する必要があります。

パラメーター：aggregator

データがダウンサンプリングされると、複数のタイムラインに沿った値が取得され、これらのタイムラインのタイムスタンプが揃えられます。各揃えられたタイムスタンプの値を集計することにより、これらのタイムラインを 1 つにマージするために集計を実行できます。タイムラインが 1 つしかない場合は、集計は実行されません。集計中、各タイムラインは各揃えられたタイムスタンプに値を持っている必要があります。揃えられたタイムスタンプに値が見つからない場合は、補間が実行されます。詳細については、以下の「補間」セクションをご参照ください。

重要

フィールドクエリでは、aggregator パラメーターは必須です。このパラメーターを none に設定できます。これは、データが集計されないことを指定します。フィールドクエリで aggregator パラメーターを指定する場合は、同じサブクエリに属する他のフィールドクエリにもこのパラメーターを指定する必要があります。TSDB では、サブクエリ内のフィールドデータの一部のみを集計することはできません。

補間

タイムラインにタイムスタンプの値がない場合、値はタイムスタンプのタイムラインに補間されます。これは、fill policy を指定せず、集計される他のタイムラインのいずれかにこのタイムスタンプの値がある場合にのみ発生します。

例を使用して、補間を説明します。この例では、sum 演算子を使用して 2 つのタイムラインをマージします。ダウンサンプリングと集計の設定は、{"downsample": "10s-avg", "aggregator": "10s-avg", "aggregator": "sum"} です。10s-avg に基づいてデータがダウンサンプリングされると、2 つのタイムラインに沿って次のタイムスタンプに値が見つかります。

値が見つかるタイムライン 1 のタイムスタンプは、t+0、t+10、t+20、および t+30 です。値が見つかるタイムライン 2 のタイムスタンプは、t+0、t+20、および t+30 です。

タイムライン 2 に沿って、t+10 タイムスタンプの値がありません。データが集計される前に、このタイムスタンプのタイムライン 2 に値が補間されます。補間方法は、集計演算子によって異なります。次の表に、演算子と補間方法を示します。

演算子	説明	補間方法
avg	平均値を返します。	線形勾配に基づいて線形補間を実行します。
count	データポイントの数を返します。	ゼロを補間します。
mimmin	最小値を返します。	最大値を補間します。
mimmax	最大値を返します。	最小値を補間します。
min	最小値を返します。	線形補間を実行します。
max	最大値を返します。	線形補間を実行します。
none	データ集計をスキップします。	ゼロを補間します。
sum	値の合計を返します。	線形補間を実行します。
zimsum	値の合計を返します。	ゼロを補間します。

パラメーター：filters

次の方法を使用して、filters パラメーターを設定できます。

tagk を使用してフィルターを指定します。
- tagk = *：タグキーのタグ値をグループ化して、同じタグ値を集計できます。
- tagk = tagv1|tagv2：タグキーの tagv1 値を集計し、タグキーの tagv2 値を集計できます。
JSON 形式でフィルターを指定します。次の表にパラメーターを示します。

パラメーター	タイプ	必須	説明	デフォルト値	例
type	String	はい	フィルタータイプ。詳細については、このトピックの「フィルタータイプ」セクションをご参照ください。	なし	literal_or
tagk	String	はい	タグのキー。	なし	host
filter	String	はい	フィルター式。	なし	web01\|web02
groupBy	Boolean	いいえ	タグ値でグループ化するかどうかを指定します。	false	false

フィルタータイプ

パラメーター	例	説明
literal_or	web01\|web02	各 tagv の値が集計されます。このフィルターでは大文字と小文字が区別されます。
wildcard	*.example.com	各 tagv に指定されたワイルドカードを含むタグ値が集計されます。このフィルターでは大文字と小文字が区別されます。

リクエストの例

フィルター付きのリクエストの例

リクエスト本文：

{
    "start" : 1346846400, // 開始時刻
    "end" :   1346846411, // 終了時刻
    "msResolution" : true, // ミリ秒単位
    "queries" : [
        {
            "metric" : "wind", // メトリック名 wind
            "fields" : [
                {
                    "field" : "speed", // フィールド speed
                    "aggregator" : "none", // 集計なし
                    "alias" : "column_speed" // エイリアス column_speed
                },
                {
                      "field" : "*", // 全てのフィールド
                    "aggregator" : "none", // 集計なし
                    "alias" : "column_" // エイリアス column_
                }
            ],
            "filters" : [
                {
                    "filter" : "IOTE_8859_0005|IOTE_8859_0004", // フィルター IOTE_8859_0005 または IOTE_8859_0004
                    "tagk" : "sensor", // タグキー sensor
                    "type" : "literal_or" // フィルタータイプ literal_or
                }
            ]
        }
    ]
}

クエリ結果

クエリが成功すると、HTTP ステータスコード 200 が返され、レスポンスは JSON 形式で返されます。次の表に、レスポンスパラメーターを示します。

パラメーター	説明
metric	メトリック名。
columns	返される列。
tags	値が集計されなかったタグ。
aggregateTags	値が集計されたタグ。
values	返されるタプル。

レスポンスの例：

次のサンプルコードは、aggregator パラメーターが none に設定されている場合のクエリ結果を示しています。

[
   {
      "metric":"wind", // メトリック名
      "columns":[ // 列
         "timestamp", // タイムスタンプ
         "column_speed", // speed 列
         "column_description", // description 列
         "column_direction", // direction 列
         "column_level", // level 列
         "column_speed" // speed 列
      ],
      "tags":{ // タグ
         "city":"hangzhou", // タグキー city, タグ値 hangzhou
         "country":"china", // タグキー country, タグ値 china
         "province":"zhejiang", // タグキー province, タグ値 zhejiang
         "sensor":"IOTE_8859_0005" // タグキー sensor, タグ値 IOTE_8859_0005
      },
      "aggregatedTags":[], // 集計されたタグなし
      "values":[ // 値
         [ 1346846406000, null, "Fresh breeze", "East", 0.5, null ], // タイムスタンプ 1346846406000 のデータ
         [ 1346846407000, null, "Fresh breeze", "South", 1.5, null ] // タイムスタンプ 1346846407000 のデータ
   },
   {
      "metric":"wind", // メトリック名
      "columns":[ // 列
         "timestamp", // タイムスタンプ
         "column_speed", // speed 列
         "column_description", // description 列
         "column_direction", // direction 列
         "column_level", // level 列
         "column_speed" // speed 列
      ],
      "tags":{ // タグ
         "city":"hangzhou", // タグキー city, タグ値 hangzhou
         "country":"china", // タグキー country, タグ値 china
         "province":"zhejiang", // タグキー province, タグ値 zhejiang
         "sensor":"IOTE_8859_0004" // タグキー sensor, タグ値 IOTE_8859_0004
      },
      "aggregatedTags":[], // 集計されたタグなし
      "values":[ // 値
         [ 1346846400000, 40.4, "Fresh breeze", "East", 0.4, 40.4 ], // タイムスタンプ 1346846400000 のデータ
         [ 1346846401000, 41.4, "Fresh breeze", "South", 1.4, 41.4 ], // タイムスタンプ 1346846401000 のデータ
         [ 1346846402000, 42.4, "Fresh breeze", "West", 2.4, 42.4 ], // タイムスタンプ 1346846402000 のデータ
         [ 1346846403000, 43.4, "Fresh breeze", "North", 3.4,43.4 ] // タイムスタンプ 1346846403000 のデータ
   }
]

次のサンプルコードは、aggregator パラメーターが avg に設定されている場合のクエリ結果を示しています。結果は、杭州市のすべてのセンサーに基づいて、平均風速と平均風レベルを示しています。

[
  {
    "metric": "wind", // メトリック名
    "columns": [ // 列
      "timestamp", // タイムスタンプ
      "avg_level", // 平均レベル
      "avg_speed" // 平均速度
    ],
    "tags": { // タグ
      "city": "hangzhou" // タグキー city, タグ値 hangzhou
    },
    "aggregatedTags": [ // 集計されたタグ
      "country", // タグキー country
      "province", // タグキー province
      "sensor" // タグキー sensor
    ],
    "values": [ // 値
      [1346846400000, 0.25, 40.25], // タイムスタンプ 1346846400000 のデータ
      [1346846401000, 1.25, 41.25], // タイムスタンプ 1346846401000 のデータ
      [1346846402000, 2.5, 42.5], // タイムスタンプ 1346846402000 のデータ
      [1346846411000, 5.5, null] // タイムスタンプ 1346846411000 のデータ
    ]
  }
]

パラメーター：hint

シナリオ

ほとんどの場合、クエリヒントはクエリの応答時間を短縮するために使用されます。たとえば、タグ A とタグ B が指定されていて、タグ B にヒットしたタイムラインがタグ A にヒットしたタイムラインに含まれているとします。この場合、タグ A にヒットしたタイムラインからはデータは読み取られません。タグ A にヒットしたタイムラインのセットとタグ B にヒットしたタイムラインのセットの共通部分は、タグ B にヒットしたタイムラインのセットと同じです。

形式の説明

現在の TSDB バージョンでは、ヒントで tagk パラメーターのみを使用してクエリインデックスを制限できます。
tagk パラメーターで指定されたタグキーと値のペアでは、タグキーのタグ値は同じである必要があります。有効な値：0 と 1。タグ値が 0 の場合、タグキーに対応するインデックスは使用されません。タグ値が 1 の場合、タグキーに対応するインデックスが使用されます。

バージョンの説明

クエリヒント機能は、TSDB V2.6.1 以降でサポートされています。

リクエストの例

サブクエリに適用されるヒント

{
  "queries": [
    {
      "metric": "demo.mf", // メトリック名
      "tags": { // タグ
        "sensor": "IOTE_8859_0001", // タグキー sensor, タグ値 IOTE_8859_0001
        "city": "hangzhou", // タグキー city, タグ値 hangzhou
        "province": "zhejiang", // タグキー province, タグ値 zhejiang
        "country": "china" // タグキー country, タグ値 china
      },
      "fields": [ // フィールド
        "speed" // フィールド speed
      ],
      "hint": { // ヒント
        "tagk": { // タグキー
          "dc": 1 // タグキー dc のインデックスを使用する
        }
      }
    }
  ]
}

クエリ全体に適用されるヒント

{
  "queries": [
    {
      "metric": "demo.mf", // メトリック名
      "tags": { // タグ
        "sensor": "IOTE_8859_0001", // タグキー sensor, タグ値 IOTE_8859_0001
        "city": "hangzhou", // タグキー city, タグ値 hangzhou
        "province": "zhejiang", // タグキー province, タグ値 zhejiang
        "country": "china" // タグキー country, タグ値 china
      },
      "fields": [ // フィールド
        "speed" // フィールド speed
      ]
    }
  ],
  "hint": { // ヒント
    "tagk": { // タグキー
      "dc": 1 // タグキー dc のインデックスを使用する
    }
  }
}

例外

tagk パラメーターで指定されたキーと値のペアのタグ値に 0 と 1 の両方が含まれている場合、エラーが返されます。

{
  "start": 1346846400, // 開始時刻
  "end": 1346846400, // 終了時刻
  "queries": [
    {
      "aggregator": "none", // 集計なし
      "metric": "sys.cpu.nice", // メトリック名
      "tags": { // タグ
        "dc": "lga", // タグキー dc, タグ値 lga
        "host": "web01" // タグキー host, タグ値 web01
      }
    }
  ],
  "hint": { // ヒント
    "tagk": { // タグキー
      "dc": 1, // タグキー dc のインデックスを使用する
      "host": 0 // タグキー host のインデックスを使用しない
    }
  }
}

次のエラーメッセージが返されます。

{
    "error": {
        "code": 400,
        "message": "ヒントの値は 0 または 1 のみで、0 と 1 の両方があってはなりません", // ヒントの値は 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=[])"
    }
}

tagk パラメーターで指定されたキーと値のペアのタグ値が 0 または 1 でない場合、エラーが返されます。

{
  "start": 1346846400, // 開始時刻
  "end": 1346846400, // 終了時刻
  "queries": [
    {
      "aggregator": "none", // 集計なし
      "metric": "sys.cpu.nice", // メトリック名
      "tags": { // タグ
        "dc": "lga", // タグキー dc, タグ値 lga
        "host": "web01" // タグキー host, タグ値 web01
      }
    }
  ],
  "hint": { // ヒント
    "tagk": { // タグキー
      "dc": 100 // タグキー dc の値が不正
    }
  }
}

次のエラーメッセージが返されます。

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