DQL データクエリ(旧版)¶
POST /api/v1/df/query_data
GET /api/v1/df/query_data
概要¶
クエリバッチ単位で DQL または PromQL のデータを取得します。このエンドポイントは旧版の GET および POST 呼び出しと互換性があります。
呼び出し前の準備と使用手順¶
GET では JSON オブジェクトを URL エンコードした body に格納し、POST では JSON を直接送信できます。旧 GET は空でない queries_body を優先して処理し、そのパスでのみトップレベルの search_after を認識します。既存の POST 単一クエリ形式では、トップレベルの qtype と query を使用できます。新しいクライアントを接続する場合は、クエリ v1 を使用してください。
例に示すメジャーメントとフィールドは、ワークスペースで収集済みのデータに置き換える必要があります。これらはメジャーメント一覧およびメジャーメントスキーマから取得できます。時間範囲はデータが存在する期間に変更してください。レスポンスを解析する際は、warnings または query_error を項目ごとに確認し、続きのページではその項目自身のカーソルを使用します。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | 現在のワークスペースの OpenAPI Key。 例: <DF-API-KEY>取得・入力方法: 対象ワークスペースの API Key 管理で、クエリ権限を持つ認証情報を取得します。 |
Query リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| body | string | 条件付き必須 | 完全なクエリ JSON オブジェクト文字列。 null 許可: False 例: {"queries":[{"qtype":"dql","query":{"q":"M::`cpu`:(`usage_idle`)","timeRange":[1785427200000,1785430800000],"limit":5}}]}取得・入力方法: クエリオブジェクトを一度だけシリアライズし、URL エンコードします(例: curl --data-urlencode)。 |
| queries_body | string | 条件付き必須 | 空でない場合は body より優先されます。旧クライアントとの互換用です。 null 許可: False 例: {"queries":[{"qtype":"dql","query":{"q":"M::`cpu`:(`usage_idle`)","timeRange":[1785427200000,1785430800000],"limit":5}}]}取得・入力方法: queries を含むオブジェクトをシリアライズし、curl --data-urlencode で送信します。 |
| search_after | string | queries_body のパスのみで読み取られます。初回のクエリでは省略します。 null 許可: False 例: [1785427200000,"cursor-example"]取得・入力方法: 同じクエリの前ページが実際に返した配列を JSON シリアライズし、URL エンコードします。 |
パラメータ補足説明¶
クエリの説明
このエンドポイントは旧版互換のエントリポイントです。新規接続では POST /api/v1/df/query_data_v1 の使用を推奨します。旧版の GET は引き続き body=<URL エンコードされた JSON> でパラメータを渡します。JSON を二重エンコードしないでください。
このエンドポイントは POST と GET の両方をサポートしており、どちらの方式でも以下のバッチクエリオブジェクトをサポートします。
- POST: 完全なパラメータを
application/jsonの request body として渡します。 - GET: HTTP entity body は使用せず、クエリ文字列で
body=<完全な JSON object 文字列>として渡します。クライアントはbodyパラメータを URL エンコードする必要があります。 - トップレベルは JSON object である必要があり、二重に JSON エンコードされた string、array、null、number、boolean は受け付けません。
クロスワークスペース/クロスサイトクエリでは、1 つのリクエスト内のすべての queries[*] が同一の targetRegion を指している必要があります。複数のサイトをクエリする必要がある場合は、サイトごとにリクエストを分割し、クライアント側で結果をマージしてください。対象ワークスペースと targetRegion は /api/v1/wksp_share/granted_ws_list から取得します。詳細はOpenAPI クロスサイトデータクエリを参照してください。
レスポンスの content.data[i].warnings[] には DQLDataAccessScopeRestricted が含まれる場合があります。
details[0].metadata.namespaceは今回loggingで固定です。details[0].metadata.restriction=partialは、権限のあるログインデックスのデータのみを返すことを示します。details[0].metadata.restriction=allは、関連するログインデックスにデータアクセス権限がなく、空の結果を返すことを示します。-
HTTP ステータスコードは 200 のままで、warning は GuanceDB/Kodo の既存 warning と共存します。
-
クエリ文字列の要素フィールド説明
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| body | string | queries_body とのいずれか一方 | クエリリクエストボディ |
| queries_body | string | body とのいずれか一方 | (互換パラメータ)queries 配列を含む JSON オブジェクト文字列 |
| search_after | string | (互換パラメータ、queries_body 専用)ページングデータのクエリ。初回のクエリでは省略します。さらにページングデータをクエリする必要がある場合は、前回のクエリ結果に含まれる search_after フィールドを付加して、後続のデータをクエリします。 |
body と互換パラメータ queries_body はいずれも条件付き必須パラメータです。GET では、空でなく正当な JSON オブジェクトを少なくとも 1 つ提供してください。両方を提供した場合は、空でない queries_body が優先されます。
- 通常のバッチクエリの JSON オブジェクト
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| queries | array | Y | 複数コマンドのクエリ。内容は query オブジェクトからなるリストです。 |
| fieldTagDescNeeded | boolean | field または tag の説明情報が必要かどうか |
- queries[*] のメンバーパラメータ構造
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| qtype | string | デフォルトは dql。クエリ文のタイプです。dql: DQL クエリ文;promql: PromQL クエリ文。例 dql。 |
|
| query | json | Y | クエリ構造。例 {"q":"M::`cpu`:(`usage_idle`)","timeRange":[1785427200000,1785430800000],"limit":5}。 |
| query.q | string | qtype のタイプと一致するクエリ文(例: dql または promql のクエリ文)。例 M::`cpu`:(`usage_idle`)。クエリツールから文をコピーするか、メジャーメントスキーマ/ログスキーマのフィールド名に従って記述します。 |
|
| query.ignore_cache | boolean | キャッシュを無効にするかどうか。デフォルトは false で、キャッシュを使用することを示します。例 false。 |
|
| query.disable_streaming_aggregation | boolean | ストリーミング集約を無効にするかどうか。デフォルトは false です。明示的に true を渡すと無効化し、明示的に false を渡すと使用を許可します。例 false。 |
|
| query.promqlType | enum | qtype=promql の場合に有効です。指定可能な値は instantQuery、rangeQuery で、デフォルトは rangeQuery です。例 rangeQuery。 |
|
| query.highlight | boolean | ハイライトデータを表示するかどうか。例 false。 |
|
| query.timeRange | array | 時間範囲のタイムスタンプリスト。DQL / PromQL の開始時刻と終了時刻は同じ単位(秒、ミリ秒、マイクロ秒、ナノ秒)を使用する必要があり、混在させた場合は HTTP 400 ft.TimeRangeUnitMismatch を返します。ページングカーソルは独立して保持されます。例 [1785427200000,1785430800000]。必要なクエリウィンドウを同じ精度の 2 つのタイムスタンプに置き換えてください。Unix ミリ秒を推奨します。 |
|
| query.disableMultipleField | bool | 単一列モードを有効にするかどうか。デフォルトは true です。例 true。 |
|
| query.showLabel | bool | オブジェクトの labels を表示するかどうか。デフォルトは false です。例 false。 |
|
| query.funcList | array | DQL の戻り値を再度集約して修飾します。選択した集約関数に従って処理されます。例 ["last"]。 |
|
| query.slimit | integer | 時系列のグループサイズ。メトリクスクエリでのみ有効です。例 10。 |
|
| query.soffset | integer | 時系列のグループオフセット。例 10。 |
|
| query.limit | integer | ページサイズ。例 5。 |
|
| query.offset | integer | ページオフセット。例 5。 |
|
| query.orderby | array | ソートリスト。構造は {fieldName: method} です。メジャーメントクエリでは fieldName=time のみサポートし、method には desc、asc を指定できます。例 [{"time":"desc"}]。 |
|
| query.density | string | レスポンスのポイント密度。優先度は autoDensity より低く、DQL 文で設定された密度より高くなります。例 medium。 |
|
| query.interval | number | 時間スライスの間隔。Kodo の int64 範囲に変換可能で、1ms 以上の整数ミリ秒に変換できる正数のみを受け付けます。デフォルトの単位は秒で、interval_unit によりミリ秒を指定できます。例 60。 |
|
| query.interval_unit | string | interval の単位。s、ms を指定でき、デフォルトは s です。例 s。 |
|
| query.search_after | array | ページングマーカー。現在のエンドポイントが返すページングマーカーで、次のリクエスト時に渡します。例 [1785427200000,"cursor-example"]。続きのページでは、前回の同じクエリが実際に返した配列をコピーする必要があります。 |
|
| query.maxPointCount | integer | 最大ポイント数。例 360。 |
|
| query.workspaceUUID | string | クエリ対象の単一の認可元ワークスペース UUID。* は targetRegion 内のすべての認可済みワークスペースをクエリすることを示します。例 wksp_example。 |
|
| query.workspaceUUIDs | array | クエリ対象の認可元ワークスペース UUID のリスト。空でない場合は query.workspaceUUID より優先されます。同じリストは同一サイトに属している必要があります。["*"] は targetRegion 内のすべての認可済みワークスペースをクエリすることを示します。2 つのフィールドを同時に渡さないことを推奨します。例 ["wksp_example"]。 |
|
| query.targetRegion | string | 認可元ワークスペースが属するサイトの regionCode。/wksp_share/granted_ws_list から、対象の workspaceUUID と同じグループの regionCode を取得します。明示的なクロスサイトの場合は認可元の regionCode を渡します。ワイルドカードかつ省略時は現在のサイトをクエリします。例 example-region。 |
|
| query.output_format | string | lineprotocol: ラインプロトコル出力。デフォルトで未指定の場合は、既存の出力形式が変更されずに維持されます。例 lineprotocol。 |
|
| query.cursor_time | integer | 分段クエリのしきい値。最初の分段クエリでは end_time を設定し、以降はレスポンスの next_cursor_time を渡します。例 1785430800000。続きのページではレスポンスの next_cursor_time を使用します。 |
|
| query.cursor_token | string | ページングクエリトークン(エンジンが返す cursor_token の値)。ページングクエリ時には、前回のクエリが返した next_cursor_token を今回のクエリの cursor_token に設定する必要があります。cursor_token を付けないリクエストでは、ページ送り時に同じタイムスタンプのデータがスキップされる可能性があります。例 cursor-example。続きのページではレスポンスの next_cursor_token を使用します。 |
|
| query.disable_sampling | bool | サンプリング無効化スイッチ。デフォルト値は false です。例 false。 |
|
| query.disable_truncate | bool | 返却内容の切り捨てを無効にするかどうか。デフォルトは false で、切り捨てを許可することを示します。例 false。 |
- レスポンスのポイント密度
densityパラメータ値の説明
| 指定可能な値 | 説明 |
|---|---|
| lower | 低め、60 ポイント |
| low | 低、180 ポイント |
| medium | 中、360 ポイント |
| high | 高、720 ポイント |
-
ポイント密度パラメータの優先度に注意してください。最大密度は
density[high]です。* interval は density および DQL のポイント密度設定より優先されます。maxPointCount により、導出されるポイント数をさらに制限できます。 -
よくあるクエリの説明
- OpenAPI クロスサイトデータクエリ
データの可視範囲は、API Key の有効な権限、ワークスペースの認可、データアクセスルールによって決まります。
リクエスト例¶
curl --get 'https://openapi.guance.com/api/v1/df/query_data' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode 'body={"queries":[{"qtype":"dql","query":{"q":"M::`cpu`:(`usage_idle`)","timeRange":[1785427200000,1785430800000],"limit":5}}]}'
旧クライアントで queries_body を使用する例
curl --get 'https://openapi.guance.com/api/v1/df/query_data' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode 'queries_body={"queries":[{"qtype":"dql","query":{"q":"M::`cpu`:(`usage_idle`)","timeRange":[1785427200000,1785430800000],"limit":5}}]}'
レスポンス¶
HTTP 200、application/json。結果とエラーはクエリ項目ごとに読み取ります。
| フィールド | 型 | 説明 |
|---|---|---|
| content.data | array<object> |
クエリが返すバッチ結果。クエリ項目ごとに解析します。 |
| content.data[].series | array<object> |
データシリーズ。データがない場合やクエリ項目が失敗した場合は空になることがあります。 |
| content.data[].series[].columns | array<string> |
シリーズの列名。 |
| content.data[].series[].values | array | columns の順序に並んだ結果行。 |
| content.data[].series[].name | string | エンジンとクエリタイプに応じて返されるシリーズ名。 |
| content.data[].series[].units | array | columns の順序で返される単位。要素は文字列または null です。このフィールドは省略される場合があります。 |
| content.data[].series[].tags | object | タグでグループ化した場合にグループ情報が返されることがあります。 |
| content.data[].column_names | array<string> |
一部のエンジンでは列名を別途提供します。 |
| content.data[].complete | boolean | エンジンが結果を完全と報告したかどうか。 |
| content.data[].is_running | boolean | クエリ項目がまだ実行中かどうか。 |
| content.data[].search_after | array | 旧分段ページングカーソル。同じクエリの続きのページでのみ使用します。 |
| content.data[].next_cursor_time | integer | 新しいカーソルの時刻。負の値はそれ以上のレコードがないことを示します。 |
| content.data[].next_cursor_token | string | 新しいカーソルに対応するマーカー。空になることがあります。 |
| content.data[].warnings | array<object> |
クエリの警告。一部のインデックスが制限されている場合でも HTTP 200 が返されることがあります。 |
| content.data[].query_error | object | クエリ単項目のエラーオブジェクト。HTTP 200 と同時に返されることがあります。 |
| content.data[].query_error.errorCode | string | 単項目のエラー識別子。 |
| content.data[].query_error.errorType | integer | 通常の DQL クエリエンジンが返すエラー種別。実際のレスポンスに応じて提供されます。 |
| content.data[].query_error.error | string | 一部の通常 DQL エラーで提供されるテキスト。 |
| content.declaration | object または null | ワークスペースの宣言。 |
{
"code": 200,
"content": {
"data": [
{
"column_names": [
"time",
"usage_idle"
],
"complete": true,
"is_running": false,
"series": [
{
"columns": [
"time",
"usage_idle"
],
"values": [
[
1785427260000,
91.5
]
]
}
]
}
],
"declaration": null
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 400 | ft.JsonFormatError | 旧版互換エントリポイントがパラメータを解析できない、または JSON オブジェクトにクエリ内容がない | 一部の JSON ファイルの形式が誤っています。 | GET では URL エンコードした body を渡し、POST では JSON オブジェクトを渡します。 |
| 400 | ft.TimeRangeUnitMismatch | timeRange の開始時刻と終了時刻が異なる単位 | 開始時刻と終了時刻の単位が一致していません。 | 同じ精度のタイムスタンプに統一してください。 |
| 403 | ft.ForbiddenQuery | API Key に目的のデータをクエリする権限がない、または目的のサイトが権限エラーでクロスサイトクエリを拒否した | DQL クエリ権限がありません。 | 対象ワークスペースの認可と対象サイトを確認してください。 |
| 406 | ft.InvalidParameter | interval または interval_unit が要件を満たさない | パラメータが無効です。 | 単位が s/ms であることを確認し、正の整数ミリ秒に換算できる必要があります。 |
| 406 | ft.DqlParseError | DQL クエリ文を解析できない | クエリ文の解析に失敗しました。詳細情報が含まれる場合があります。 | まずクエリツールで構文を検証してください。 |
| 406 | ft.UnsupportMultiSiteQuery | バッチクエリが複数のサイトにまたがっている | マルチサイトのワークスペースクエリはサポートしていません。 | サイトごとに個別に送信してください。 |
| 406 | ft.workspaceUnauthorized | 認可されていないワークスペースを明示的に要求した | メッセージに未認可のワークスペースが示されます。 | 認可済みワークスペース一覧から有効な識別子を取得し直してください。 |
| 406 | ft.NotFoundWorkspaceAuthorizationCfg | クロスサイトクエリで対応する認可が見つからない | ワークスペース認可情報が見つかりません。 | サイトとワークスペース間の共有設定を確認してください。 |
| 406 | ft.OpenapiDqlLoggingWildcardIndexForbidden | インデックス設定が全インデックスクエリを制限している | ログインデックスを明示的に指定してください。 | ログインデックス一覧からインデックス名を取得してください。 |
| 406 | ft.OpenapiDqlLoggingIndexLimitExceeded | ログインデックスの数が設定された制限を超えている | メッセージに 1 回でクエリ可能なインデックス数が含まれます。 | インデックス範囲を絞ってください。 |
| 503 | ft.QueryServiceUnavailable | クエリサービスが一時的に利用できない | クエリサービスは一時的に利用できません。しばらくしてから再試行してください。 | content.retryable と実際の状態に応じてバックオフしながら再試行してください。 |
| 406 | ft.ParameterValidationFailed | 宣言されていない Query パラメータが渡された | リクエストフィールドの検証に失敗しました。 | パラメータ表にあるクエリフィールドのみを使用してください。 |