DQL データ非同期クエリ¶
POST /api/v1/df/asynchronous/query_data
GET /api/v1/df/asynchronous/query_data
概要¶
ワークスペースの非同期データクエリを送信またはポーリングします。通常の DQL/PromQL および QueryHub バッチをサポートします。
呼び出し前の確認と使用手順¶
現在のインターフェースは freeEdition タイプのワークスペースをサポートしていません。先にワークスペースのバージョンを確認してください。通常クエリは GET と互換性があります。POST と同じ完全なオブジェクトを URL エンコードした body パラメータに格納します。QueryHub は POST JSON のみをサポートします。現在のワークスペースでクエリ権限を持つ API Key を使用し、常に POST application/json を推奨します。通常のメジャーメントとフィールドは、メジャーメント一覧 と メジャーメントスキーマ から取得します。クエリ構文は 通常クエリ v1 を参照してください。初回は async_id を渡しません。レスポンスの各項目で is_running=true の場合、その項目に限り async_id をそのまま返します。通常クエリでは元の query を保持します。QueryHub のポーリングでは qtype=queryhub、uuid、async_id のみを渡すことができます。項目ごとに処理し、完了済みの項目は再送信しないでください。意図せずクエリが再開されるのを防ぎます。
通常クエリは、まず同期的に待機してから非同期に切り替わる場合があります。リポジトリの待機しきい値はデフォルト 50 秒、総検索予算はデフォルト 2 分で、サイト側で上書きできます。async_timeout は切り替えしきい値を調整しますが、Front の search_timeout フィールドでこの OpenAPI の予算を変更することはできません。外部関数クエリでは短時間キャッシュを待機する場合があり、デフォルトでは最大 10 秒、0.5 秒ごとに確認します。タスクが即座に返されることを前提にしてはいけません。ホスト型 outer_datasource のクエリチャネルは OpenAPI でアクセスが拒否されます。QueryHub は独立したプロトコルを使用します。
QueryHub では、管理者がデータソースを設定し有効化している必要があります。クエリ項目は最大 20 個、ワークスペース全体で最大 20 個のアクティブタスクです。pending は登録済みであることのみを示し、タスクの配信に失敗した場合はバックグラウンドでの再配信を待つことがあります。タスクは元のワークスペースと元の API Key にバインドされ、送信から 300 秒で期限切れになります。ポーリングや実行完了によって延長されることはありません。is_running=true の項目のみをポーリングしてください。QueryHub の終端状態では async_id がクリアされ、通常クエリの失敗項目は ID が非空でもポーリングを停止する必要があります。HTTP 200 と success=true はバッチの返却が成功したことのみを示し、各項目のクエリ成功を意味しません。query_error/errorInfo、query_status、warnings を必ず確認してください。
非同期クエリのキャンセル から、現在の Key で送信した QueryHub タスクをキャンセルできます。このキャンセル入口は通常 DQL のタスク ID を受け付けません。キャンセルは結果にマークを付けて破棄しますが、実行済みの基盤クエリが中断されることは保証されません。クエリ結果のカーソルは同一クエリのデータページ継続にのみ使用し、非同期タスク ID として扱うことはできません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Query リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| body | string | 通常 GET の完全な JSON オブジェクト文字列です。QueryHub はこの方式を受け付けず、POST JSON のみです。 例: {"queries": [{"qtype": "dql", "async_timeout": "5s", "query": {"q": "M::`cpu`:(`usage_idle`)", "timeRange": [1785427200000, 1785430800000], "limit": 5}}]}取得または入力方法: 通常 GET クエリでのみ使用します。同じ完全な JSON オブジェクトを 1 回シリアライズして URL エンコードします(例: curl --data-urlencode)。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| queries[*] | object | 1 つのクエリ項目です。qtype によってプロトコルが決まります。 例: {"qtype": "dql", "query": {"q": "M::`cpu`:(`usage_idle`)", "timeRange": [1785427200000, 1785430800000]}}取得または入力方法: 本ページの通常 DQL または QueryHub の例に従ってオブジェクトを構築します。 |
|
| queries[*].qtype | string | 通常クエリのデフォルトは dql で、promql および設定済みの外部関数タイプもサポートします。QueryHub では queryhub が必須で、ポーリング時も保持する必要があります。 例: dql取得または入力方法: 実際のクエリ言語に応じて選択します。ホスト型 outer_datasource チャネルはこの OpenAPI ではアクセスが拒否されるため、Front の機能をそのまま流用することはできません。 |
|
| queries[*].uuid | string | QueryHub の任意のクライアント識別子で、レスポンスにエコーされます。タスク ID ではなく、ポーリングには使用しません。 例: cpu-query取得または入力方法: 呼び出し元が結果を照合するための安定したクエリ項目識別子を生成します。 |
|
| queries[*].async_id | string | 初回クエリでは省略するか空文字列にします。ポーリングでまだ実行中の同一項目にのみ、元のレスポンス ID を返します。QueryHub では qhtask_ プレフィックスが付き、通常の ID と混在できません。 例: <async-id-from-response>取得または入力方法: その項目のレスポンス content.data[].async_id を取得します。元のワークスペースと元の API Key を維持する必要があります。 |
|
| queries[*].async_timeout | string | 通常クエリで同期待機から非同期に切り替えるまでの待機しきい値です。省略時はサイトのデフォルトを使用し、リポジトリのデフォルトは 50s です。タスク全体の実行予算ではなく、QueryHub ではこのフィールドを使用しません。 例: 5s取得または入力方法: 呼び出し側の待機能力に応じて単位付きの時間を選択します。実際にサポートされる範囲は現在のクエリエンジンに依存します。 |
|
| queries[*].query | object | 通常クエリでは初回もポーリング時も元のクエリオブジェクトを提供します。QueryHub では初回は必須で、ポーリング時は省略できます。両プロトコルのサブフィールドは以下のとおりです。 例: {"q": "M::`cpu`:(`usage_idle`)", "timeRange": [1785427200000, 1785430800000], "limit": 5}取得または入力方法: クエリ文と時間は業務データの範囲から決定し、データソース ID は管理者が提供します。 |
|
| queries[*].query.q | string | 通常の DQL/PromQL 文です。通常クエリでは有効な非空の文を提供する必要があります。 例: M::`cpu`:(`usage_idle`)取得または入力方法: メジャーメント一覧 と メジャーメントスキーマ から実際のメジャーメントとフィールドを取得し、クエリツールで文を事前に検証してください。 |
|
| queries[*].query.timeRange | array | 通常クエリの開始時刻と終了時刻です。Unix ミリ秒の 2 要素配列に統一することを推奨します。両端で単位を混在させないでください。 例: [1785427200000, 1785430800000]取得または入力方法: 業務イベント時刻または JavaScript Date.getTime() でクエリ区間を選択します。 |
|
| queries[*].query.timeRange[*] | integer | 同じ精度のタイムスタンプです。Unix ミリ秒を推奨します。 例: 1785427200000取得または入力方法: 開始と終了に同じ単位の整数を使用します。 |
|
| queries[*].query.limit | integer | 通常クエリのレコード件数制限です。整数に変換されますが、各エンジンの最終的な最大可読行数を表すものではありません。 例: 100取得または入力方法: レスポンスボディの要件に応じて正の整数を選択し、まず小さいバッチで読み取ります。 |
|
| queries[*].query.offset | integer | 通常クエリのレコードオフセットです。limit と組み合わせて使用し、バックエンドのサポート状況はクエリに依存します。 例: 0取得または入力方法: それまでに読み取った件数を指定し、先頭ページは 0 です。 |
|
| queries[*].query.slimit | integer | 通常クエリのシリーズ数制限です。 例: 10取得または入力方法: 集計グループが多い場合に必要なシリーズ数を選択します。 |
|
| queries[*].query.soffset | integer | 通常クエリのシリーズオフセットです。 例: 0取得または入力方法: それまでに読み取ったシリーズ数を指定します。 |
|
| queries[*].query.tz | string | 通常クエリの IANA タイムゾーンです。デフォルトは Asia/Shanghai で、時間スライス/整列に使用します。 例: Asia/Shanghai取得または入力方法: 業務の実際のタイムゾーン識別子を使用します。 |
|
| queries[*].query.interval | number | 通常クエリの時間スライス値です。正確に正の整数ミリ秒へ換算できる必要があります。60s のような単位付き文字列はサポートしません。 例: 60取得または入力方法: 必要なスライス粒度に応じて数値を指定し、interval_unit で s/ms を指定します。 |
|
| queries[*].query.interval_unit | string | スライス単位です。s または ms のみで、デフォルトは s です。 例: s取得または入力方法: 秒は s、ミリ秒は ms を指定します。 |
|
| queries[*].query.align_time | boolean | 通常クエリのスライス開始時刻を整列するかどうかのスイッチです。省略時はエンジンのデフォルト動作に任せます。 例: false取得または入力方法: タイムゾーンに合わせて集計境界を整列する必要がある場合に使用します。 |
|
| queries[*].query.density | string | 通常クエリのポイント密度名で、サイト設定によって定義されます。リポジトリのデフォルトでは lower/low/medium/high がそれぞれ 60/180/360/720 です。 例: medium取得または入力方法: interval または maxPointCount で明示的に制御することを優先してください。密度を使用する前にサイトがサポートする値を確認してください。 |
|
| queries[*].query.maxPointCount | integer | 通常クエリの最大ポイント数です。interval によるポイント数と同時に存在する場合は小さい方の値が採用されます。 例: 360取得または入力方法: グラフに表示可能なポイント数に基づいて正の整数を選択します。 |
|
| queries[*].query.workspaceUUID | string | 通常クエリの単一の認可対象ワークスペースです。指定しない場合は現在のワークスペースを使用します。QueryHub では禁止されています。 例: wksp_target取得または入力方法: ワークスペース共有認可設定から実際の対象ワークスペース UUID を取得します。 |
|
| queries[*].query.workspaceUUIDs | array<string> |
通常クエリの複数の認可対象ワークスペースです。単一の workspaceUUID より優先されます。QueryHub では禁止されています。 例: ["wksp_target"]取得または入力方法: ワークスペース共有認可設定から同一サイトのワークスペース一覧を取得します。 |
|
| queries[*].query.workspaceUUIDs[*] | string | 認可済みワークスペースの UUID です。 例: wksp_target取得または入力方法: 認可ワークスペース情報からコピーし、表示名は使用しません。 |
|
| queries[*].query.targetRegion | string | 通常のクロスワークスペースクエリの対象サイトです。バッチ全体で 1 つのサイトのみをサポートします。QueryHub では禁止されています。 例: <authorized-site-code>取得または入力方法: クロスサイト認可設定からサイトコードを取得し、ドメイン名から推測してはいけません。 |
|
| queries[*].query.indexes | array<string> |
通常のログクエリのインデックス名配列です。現在の Key とインデックスの制限を満たす必要があります。 例: ["default"]取得または入力方法: 現在のワークスペースのログインデックス設定から既存の名前を読み取ります。 |
|
| queries[*].query.indexes[*] | string | 実際のログインデックス名です。 例: default取得または入力方法: 設定済みのインデックス名をコピーします。 |
|
| queries[*].query.conditions | string | 通常クエリの追加 WHERE 条件です。filter 条件と AND で結合されます。エスケープされていない外部入力を含めることはできません。 例: env = 'production'取得または入力方法: 実際のフィールドに基づいて、クエリ言語に適合する条件式を構築します。 |
|
| queries[*].query.filter | object | 通常クエリの追加タグ/フィールド条件です。2 つの配列がマージされて条件フォーマットに渡されます。 例: {"tags": [], "fields": []}取得または入力方法: 複雑なフィルタは、検証済みの q または conditions に直接記述できます。 |
|
| queries[*].query.filter.tags | array<object> |
タグフィルタ条件の配列です。 例: []取得または入力方法: 本ページの条件オブジェクト構造を使用し、実際のタグ名に基づいて構築します。 |
|
| queries[*].query.filter.fields | array<object> |
フィールドフィルタ条件の配列です。 例: []取得または入力方法: 本ページの条件オブジェクト構造を使用し、実際のフィールド名に基づいて構築します。 |
|
| queries[*].query.search_after | array | 通常クエリの旧式セグメントページングカーソルです。元のクエリのページ継続にのみ使用します。 例: []取得または入力方法: その項目のレスポンス search_after をそのままコピーし、返されない場合は省略します。 |
|
| queries[*].query.cursor_time | integer | 通常のセグメントクエリで次のセグメントの開始時刻です。cursor_token とペアで継続する必要があります。 例: 1785430800000取得または入力方法: その項目のレスポンス next_cursor_time を取得します。負の値はこれ以上レコードがないことを示します。 |
|
| queries[*].query.cursor_token | string | 通常のセグメントページングマーカーで、同一時刻のレコードがスキップされるのを防ぎます。 例: <next-cursor-token>取得または入力方法: その項目のレスポンス next_cursor_token をそのままコピーし、元のフィルタと並び順を維持します。 |
|
| queries[*].query.disable_sampling | boolean | 通常クエリのセグメント無効化スイッチです。true の場合、cursor_time は有効になりません。 例: false取得または入力方法: 通常は省略します。セグメントを明確に無効化する必要がある場合にのみ true を設定します。 |
|
| queries[*].query.disable_streaming_aggregation | boolean | 通常クエリのストリーミング集計を無効化します。デフォルトは false です。実際のエンジンやコンテキストによって上書きされる場合があります。 例: false取得または入力方法: 通常はデフォルトのままにし、調査や完全な集計が明確に必要な場合に選択します。 |
|
| queries[*].query.ignore_cache | boolean | 通常クエリでクエリキャッシュを無視するエンジンパススルースイッチです。 例: false取得または入力方法: 基盤データを再クエリする必要がある場合、サイトのエンジン能力に応じて使用します。 |
|
| queries[*].query.disable_truncate | boolean | 通常クエリで返却結果の切り詰めを無効化するエンジンパススルースイッチです。バックエンドのリソース制限を回避するものではありません。 例: false取得または入力方法: 通常は省略し、完全な結果が本当に必要な場合はデータ量とエンジンのサポートを先に確認します。 |
|
| queries[*].query.disable_var_expansion | boolean | ScopeDB クエリ経路にのみ引き続きパススルーされる変数展開無効化スイッチです。 例: false取得または入力方法: 既存の明確な ScopeDB 設定が必要な場合にのみ指定し、その他のエンジンでは省略します。 |
|
| queries[*].query.enable_preflight_estimate | boolean | 通常クエリのプリフライト見積もりスイッチで、そのままエンジンに渡されます。 例: false取得または入力方法: 対象エンジンがサポートし、見積もりが必要な場合にのみ指定します。 |
|
| queries[*].query.disallow_large_query | boolean | 通常の高コストクエリ制限スイッチです。デフォルトは false です。 例: false取得または入力方法: エンジンに高コストリクエストを拒否させたい場合に使用します。実際の判定はサイトのエンジンルールに従います。 |
|
| queries[*].query.scan_completed | boolean | 通常のインデックスバッチスキャン進捗マーカーです。デフォルトは false です。 例: false取得または入力方法: エンジンがバッチスキャン状態を返した場合にのみ、元の返却値に従って継続します。 |
|
| queries[*].query.scan_index | string | 通常のインデックスバッチスキャン位置マーカーです。デフォルトは空文字列です。 例: <scan-index>取得または入力方法: 同一クエリエンジンが返したマーカーのみを使用し、初回クエリでは省略します。 |
|
| queries[*].query.promqlType | string | 通常の qtype=promql のサブタイプは instantQuery または rangeQuery で、通常の PromQL エンジンに渡されます。QueryHub の native.operation とは異なります。 例: rangeQuery取得または入力方法: 実際の PromQL クエリで使用するインスタント/レンジ方式に応じて設定します。 |
|
| queries[*].query.output_format | string | 通常クエリでエンジンがサポートする出力形式を要求できます。lineprotocol では通常の結果変換がスキップされ、series 構造は保証されません。 例: lineprotocol取得または入力方法: 通常のクライアントでは省略し、統一された series 返却を使用することを推奨します。 |
|
| queries[*].query.funcList | array | 通常クエリ結果の後処理関数リストで、最終構造に影響します。 例: []取得または入力方法: 通常は省略します。検証済みの結果変換設定のみを再利用でき、DQL 文の関数リストではありません。 |
|
| queries[*].query.needclearnone | boolean | 通常の結果変換時に空値をクリアするかどうかです。デフォルトは true です。 例: true取得または入力方法: エンジンの空値を保持したい場合は false にできますが、最終構造は結果変換に依存します。 |
|
| queries[*].query.filter.tags[*] | object | 1 つのフィルタ条件です。filters/condition を使用してネスト条件を構築することもできます。 例: {"name": "env", "operation": "=", "value": ["production"], "condition": "and"}取得または入力方法: 実際のタグまたはフィールドから名前と値を選択します。 |
|
| queries[*].query.filter.tags[*].name | string | フィールドまたはタグ名です。 例: env取得または入力方法: 実際のフィルタ要件に応じて入力し、少量のデータで先に検証します。 |
|
| queries[*].query.filter.tags[*].operation | string | 比較演算子(=、!=、in、not in、match など)です。対象の DQL サポートに従います。 例: =取得または入力方法: 実際のフィルタ要件に応じて入力し、少量のデータで先に検証します。 |
|
| queries[*].query.filter.tags[*].value | array | 比較に使用する値の配列です。 例: ["production"]取得または入力方法: 実際のフィルタ要件に応じて入力し、少量のデータで先に検証します。 |
|
| queries[*].query.filter.tags[*].condition | string | 同じグループ内の他の条件との結合ロジックです。and/or を推奨します。 例: and取得または入力方法: 実際のフィルタ要件に応じて入力し、少量のデータで先に検証します。 |
|
| queries[*].query.filter.tags[*].filters | array<object> |
任意のネスト条件配列です。各項目は同じ条件オブジェクトを再利用します。 例: []取得または入力方法: 実際のフィルタ要件に応じて入力し、少量のデータで先に検証します。 |
|
| queries[*].query.filter.fields[*] | object | 1 つのフィルタ条件です。filters/condition を使用してネスト条件を構築することもできます。 例: {"name": "env", "operation": "=", "value": ["production"], "condition": "and"}取得または入力方法: 実際のタグまたはフィールドから名前と値を選択します。 |
|
| queries[*].query.filter.fields[*].name | string | フィールドまたはタグ名です。 例: env取得または入力方法: 実際のフィルタ要件に応じて入力し、少量のデータで先に検証します。 |
|
| queries[*].query.filter.fields[*].operation | string | 比較演算子(=、!=、in、not in、match など)です。対象の DQL サポートに従います。 例: =取得または入力方法: 実際のフィルタ要件に応じて入力し、少量のデータで先に検証します。 |
|
| queries[*].query.filter.fields[*].value | array | 比較に使用する値の配列です。 例: ["production"]取得または入力方法: 実際のフィルタ要件に応じて入力し、少量のデータで先に検証します。 |
|
| queries[*].query.filter.fields[*].condition | string | 同じグループ内の他の条件との結合ロジックです。and/or を推奨します。 例: and取得または入力方法: 実際のフィルタ要件に応じて入力し、少量のデータで先に検証します。 |
|
| queries[*].query.filter.fields[*].filters | array<object> |
任意のネスト条件配列です。各項目は同じ条件オブジェクトを再利用します。 例: []取得または入力方法: 実際のフィルタ要件に応じて入力し、少量のデータで先に検証します。 |
|
| queries[*].query.datasourceId | string | 有効化済みの QueryHub データソース識別子で、接続文字列やワークスペース UUID ではありません。全体の長さは 1~128 文字で、先頭は英字または数字、以降は英数字、ドット、アンダースコア、ハイフンのみです。 例: ds_example取得または入力方法: ワークスペースのデータソース管理者がデータソース詳細から提供します。 |
|
| queries[*].query.mode | string | native は基盤のクエリ言語を使用し、dql は QueryHub DQL を使用します。初回送信時に必ず選択し、2 つのペイロードを混在させないでください。 例: native取得または入力方法: 対象データソースで有効化済みの機能に応じて native または dql を選択します。 |
|
| queries[*].query.expectedRevision | integer | 任意の設定バージョンで、1~2^64-1 です。一致しない場合は拒否され、古い接続設定でクエリすることを防ぎます。 例: 1取得または入力方法: 保存済みのデータソース設定 revision から取得し、自分でインクリメントして推測しないでください。 |
|
| queries[*].query.native | object | mode=native の場合は必須です。language に応じて下記の該当フィールドのみを送信します。 例: {"language": "sql", "statement": "SELECT 1 AS value", "parameters": []}取得または入力方法: 受信データベース/エンジンがサポートする読み取り専用のネイティブクエリを使用します。 |
|
| queries[*].query.native.language | string | sql は MySQL/Postgres、promql は Prometheus、elasticsearch は ES、mongodb は MongoDB に使用し、データソースと一致する必要があります。 例: sql取得または入力方法: 設定済みのデータソースタイプに応じて選択します。 |
|
| queries[*].query.native.statement | string | SQL または PromQL 文で、非空、最大 16384 文字です。ES/Mongo ではこのフィールドを使用しません。 例: SELECT 1 AS value取得または入力方法: 検証済みの業務クエリから構築し、値パラメータは文と分離します。 |
|
| queries[*].query.native.parameters | array | SQL のみ: 最大 128 個のスカラー バインド値で、JSON 全体は最大 32768 バイトです。string/number/boolean/null をサポートし、ネストしたオブジェクトはサポートしません。 例: []取得または入力方法: SQL プレースホルダーの順序に従って業務入力値を提供します。プレースホルダー構文は対象データソースに従います。 |
|
| queries[*].query.native.parameters[*] | JSON スカラー | SQL の単一バインド値です。 例: production取得または入力方法: 対応する業務入力を使用し、SQL 文字列へ結合しないでください。 |
|
| queries[*].query.native.operation | string | Prometheus では query/query_range、ES では search、Mongo では find/count です。SQL では指定しません。 例: query_range取得または入力方法: 選択した language に応じてサポートされる操作を選択します。 |
|
| queries[*].query.native.arguments | object | PromQL/ES/Mongo の操作パラメータで、language と operation に応じて選択します。JSON は最大 32768 バイトです。 例: {"start": 1785427200, "end": 1785430800, "step": "60s"}取得または入力方法: 以下の各フィールドの適用条件に従って提供します。 |
|
| queries[*].query.native.arguments.time | number または string | PromQL の query のみで任意の評価時刻を指定できます。エンジンの時間文字列または Unix 秒をサポートします。 例: 1785427200取得または入力方法: 業務で必要なインスタント時刻から取得し、ミリ秒をそのまま秒として渡してはいけません。 |
|
| queries[*].query.native.arguments.start | number または string | PromQL の query_range で必須の開始時刻です。Unix 秒またはエンジンの時間文字列です。 例: 1785427200取得または入力方法: 業務クエリの開始時刻を選択します。 |
|
| queries[*].query.native.arguments.end | number または string | PromQL の query_range で必須の終了時刻です。Unix 秒またはエンジンの時間文字列です。 例: 1785430800取得または入力方法: 業務クエリの終了時刻を選択し、エンジンの要件に従って開始より後にします。 |
|
| queries[*].query.native.arguments.step | number または string | PromQL の query_range で必須のステップです。数値は正である必要があり、文字列はエンジンの期間形式を使用します。 例: 60s取得または入力方法: 結果のサンプリング密度に応じて秒数または単位付き期間を選択します。 |
|
| queries[*].query.native.arguments.body | object | ES の search で必須のクエリ DSL オブジェクトです。pit フィールドを含めることはできません。 例: {"query": {"match_all": {}}, "size": 5}取得または入力方法: 対象インデックスで検証済みの ES クエリ DSL です。 |
|
| queries[*].query.native.arguments.body.動的フィールド | JSON 値 | 対象 ES がサポートするクエリ DSL フィールドです。具体的な構文はデータソースエンジンによって定義され、Studio は固定のサブフィールド表を提供しません。 例: {"match_all": {}}取得または入力方法: 対象 ES バージョンのネイティブ DSL に従って構築します。 |
|
| queries[*].query.native.arguments.filter | object | Mongo の find/count で任意のフィルタドキュメントです。 例: {"env": "production"}取得または入力方法: コレクションの実際のフィールドに基づいて Mongo フィルタを構築します。 |
|
| queries[*].query.native.arguments.projection | object | Mongo の find のみで任意のフィールド投影です。 例: {"_id": 0, "env": 1}取得または入力方法: 必要に応じて返却するフィールドに基づいて Mongo 投影ドキュメントを構築します。 |
|
| queries[*].query.native.arguments.sort | object | Mongo の find のみで任意の並び順です。JSON のキー順が並び順の優先度になります。 例: {"time": -1}取得または入力方法: 必要な並び順の優先度に従って、順序付きフィールドオブジェクトを構築します。 |
|
| queries[*].query.native.arguments.skip | integer | Mongo の find のみでスキップ件数です。非負の整数です。 例: 0取得または入力方法: それまでに読み取った件数に応じて設定します。 |
|
| queries[*].query.native.arguments.limit | integer | Mongo の find のみで件数制限です。非負の整数です。0 の実際の意味は基盤エンジンによって決まります。 例: 5取得または入力方法: 小さな正の整数を明示することを推奨します。 |
|
| queries[*].query.dql | object | mode=dql の場合のみ必須です。QueryHub DQL オブジェクトで、通常の query.q とは異なります。 例: {"dqlVersion": "queryhub/v1", "dql": "queryhub(source=\"mysql\", datasource=\"orders\")::orders:(id) {status = $status}", "parameters": {"status": "paid"}}取得または入力方法: データソースが既にサポートする QueryHub DQL 構文とテーブル名を使用し、事前に機能を検証してください。 |
|
| queries[*].query.dql.dqlVersion | string | QueryHub DQL プロトコルバージョンです。省略時は queryhub/v1 で、この値のみをサポートします。 例: queryhub/v1取得または入力方法: 固定で queryhub/v1 を使用します。 |
|
| queries[*].query.dql.dql | string | 非空の QueryHub DQL 文で、最大 16384 文字です。 例: queryhub(source="mysql", datasource="orders")::orders:(id) {status = $status}取得または入力方法: 検証済みの QueryHub データソースクエリから取得します。すべての通常 DQL 構文がそのまま使用できると仮定してはいけません。 |
|
| queries[*].query.dql.parameters | object | 最大 128 個のパラメータ名で、名前は非空かつ最大 128 文字です。値はスカラーまたは非空のスカラー配列で、JSON 全体は最大 32768 バイトです。 例: {"env": "production"}取得または入力方法: 文のパラメータ名に応じて業務値を提供します。 |
|
| queries[*].query.dql.parameters.動的パラメータ名 | JSON スカラーまたはスカラー配列 | 1 つの名前付きパラメータ値です。ネストしたオブジェクトや空配列はサポートしません。 例: production取得または入力方法: 文内の実際のパラメータ名で動的キーを置き換えます。 |
|
| queries[*].query.showLabel | boolean | 通常クエリのラベル表示スイッチで、クエリエンジンに渡されます。省略時はエンジンのデフォルトを保持します。 例: true取得または入力方法: 現在のエンジン/既存の呼び出し元で検証済みの対応設定のみを再利用し、異なるエンジン構造を混在させないでください。 |
|
| queries[*].query.disable_slimit | boolean | 通常クエリのシリーズ数制限を無効化するパススルースイッチです。サイトのリソース上限を回避するものではありません。 例: false取得または入力方法: 現在のエンジン/既存の呼び出し元で検証済みの対応設定のみを再利用し、異なるエンジン構造を混在させないでください。 |
|
| queries[*].query.is_optimized | boolean | 通常クエリの最適化スイッチで、対象クエリエンジンにそのまま渡されます。通常は省略します。 例: true取得または入力方法: 現在のエンジン/既存の呼び出し元で検証済みの対応設定のみを再利用し、異なるエンジン構造を混在させないでください。 |
|
| queries[*].query.skipTracingDataQueryRule | boolean | トレースクエリのデータクエリルール制御マーカーです。認証を回避する方法として使用せず、通常の呼び出しでは省略します。 例: false取得または入力方法: 現在のエンジン/既存の呼び出し元で検証済みの対応設定のみを再利用し、異なるエンジン構造を混在させないでください。 |
|
| queries[*].query.highlight | JSON 値 | 通常クエリのハイライト制御です。Studio は元の値を保持し、具体的な型と効果は対象エンジンのサポートによって決まります。通常は省略します。 例: true取得または入力方法: 現在のエンジン/既存の呼び出し元で検証済みの対応設定のみを再利用し、異なるエンジン構造を混在させないでください。 |
|
| queries[*].query.sls_query | JSON 値 | SLS クエリ専用の設定で、そのままパススルーされます。既存の SLS クエリテンプレートがある場合にのみテンプレートに従って提供し、他のエンジンには使用しません。 例: {}取得または入力方法: 現在のエンジン/既存の呼び出し元で検証済みの対応設定のみを再利用し、異なるエンジン構造を混在させないでください。 |
|
| queries[*].query.orderby | JSON 値 | 通常クエリのレコード並び順の旧フィールドです。Studio は非空値をそのままパススルーします。検証済みの q 文で並び順を直接指定することを推奨し、既存クライアントは元の形式を維持します。 例: []取得または入力方法: 現在のエンジン/既存の呼び出し元で検証済みの対応設定のみを再利用し、異なるエンジン構造を混在させないでください。 |
|
| queries[*].query.sorderby | JSON 値 | 通常クエリのシリーズ並び順の旧フィールドです。非空値をそのままパススルーします。既存のクエリテンプレートがある場合にのみ提供します。 例: []取得または入力方法: 現在のエンジン/既存の呼び出し元で検証済みの対応設定のみを再利用し、異なるエンジン構造を混在させないでください。 |
|
| queries[*].query.order_by | array | 通常の Doris 互換並び順配列で、要素は {column:フィールド名,order:DESC または ASC} の形式です。既存エンジンに異なる並び順プロトコルがある場合は、検証済み形式を維持してください。 例: [{"column": "time", "order": "DESC"}]取得または入力方法: 現在のエンジン/既存の呼び出し元で検証済みの対応設定のみを再利用し、異なるエンジン構造を混在させないでください。 |
|
| queries[*].query.sorder_by | array | 通常の Doris 互換並び順配列で、要素は {column:フィールド名,order:DESC または ASC} の形式です。既存エンジンに異なる並び順プロトコルがある場合は、検証済み形式を維持してください。 例: [{"column": "time", "order": "DESC"}]取得または入力方法: 現在のエンジン/既存の呼び出し元で検証済みの対応設定のみを再利用し、異なるエンジン構造を混在させないでください。 |
|
| queries[*].query.appScopes | array<object> |
明示的な RUM アプリケーションスコープで、非空配列です。各ワークスペースは 1 回だけ出現し、今回の認可ワークスペース範囲内である必要があります。指定する場合、workspaceUUID と workspaceUUIDs を同時に提供できません。 例: [{"workspaceUUID": "wksp_example", "appIds": ["app_example"]}]取得または入力方法: RUM アプリケーション設定からワークスペース UUID とアプリケーション ID を取得し、表示名や all を使用してはいけません。 |
|
| queries[*].query.appScopes[*] | object | 単一の対象ワークスペースの RUM アプリケーションスコープです。 例: {"workspaceUUID": "wksp_example", "appIds": ["app_example"]}取得または入力方法: 対象ワークスペースで認可済みの実際の RUM アプリケーション設定に従って構築します。 |
|
| queries[*].query.appScopes[*].workspaceUUID | string | 今回の認可範囲内のワークスペース UUID です。 例: wksp_example取得または入力方法: 現在のワークスペースまたは認可済みの対象ワークスペースから取得します。 |
|
| queries[*].query.appScopes[*].appIds | array<string> |
そのワークスペースの非空アプリケーション ID 配列で、重複排除されます。英数字、アンダースコア、ハイフンのみで最大 128 文字です。all はサポートしません。 例: ["app_example"]取得または入力方法: 対象ワークスペースの RUM アプリケーション設定から実際のアプリケーション ID を取得します。 |
|
| queries[*].query.appScopes[*].appIds[*] | string | 実際の RUM アプリケーション ID です。 例: app_example取得または入力方法: 対応するワークスペースの RUM アプリケーション識別子をコピーします。 |
|
| queries[*].query.disableMultipleField | boolean | 通常の結果フォーマットにおける複数フィールド制御で、実際の値は現在の結果変換ルールによって読み取られます。 例: true取得または入力方法: 通常は省略し、既存のクエリテンプレート内の明確な設定を使用します。 |
|
| fieldTagDescNeeded | boolean | 通常クエリのフィールド/タグ説明補足で、デフォルトは false です。すべてのクエリで説明フィールドが追加されるわけではありません。 null を許可: False 例: false取得または入力方法: SHOW_FIELD などの結果の型、単位、説明が必要な場合に true を設定します。 |
|
| queries | array | 通常クエリでは少なくとも 1 項目を推奨します。省略または [] の場合、成功して空の data を返すことと互換性があります。QueryHub を含む場合は 1~20 項目である必要があります。 null を許可: False 例: [{"qtype": "dql", "query": {"q": "M::`cpu`:(`usage_idle`)", "timeRange": [1785427200000, 1785430800000], "limit": 5}}]取得または入力方法: 以下の表に従って各項目を構築し、クエリ項目とレスポンス項目の順序対応を維持します。 |
パラメータ補足¶
新規クエリでは必ず async_id を省略します。content.data[i].is_running=true かつその項目の async_id が非空の場合にのみ、同じ queries[i] に戻してポーリングします。通常クエリでは元の query、対象ワークスペース、targetRegion を変更しません。QueryHub の継続では qtype=queryhub と async_id を保持し、query は省略できます。is_running=false になった時点でポーリングを停止します。古い ID がレスポンスに残っていても同様です。async_id はセッション ID でもページングカーソルでもありません。新しいクエリや他のクエリ項目に再利用することは禁止されています。実行中なのに ID がない場合、過去の ID を代用してはいけません。traceId を記録し、限定的にリトライするかサポートへ連絡してください。
通常のクロスワークスペースクエリでは、workspaceUUIDs が非空の場合に workspaceUUID より優先され、1 つのバッチでは同じ targetRegion のみをクエリします。対象ワークスペース UUID と targetRegion は、/wksp_share/granted_ws_list の同じグループの workspaceUUID と regionCode から取得する必要があります。ワイルドカード workspaceUUID="*" または workspaceUUIDs=["*"] の場合は、非空の targetRegion を明示的に提供する必要があり、そのサイトで認可済みのワークスペースのみをクエリします。コンソールのドメイン名や toRegionCode を regionCode として扱わないでください。完全な手順は OpenAPI クロスサイトデータクエリ および 認可ワークスペース一覧 を参照してください。QueryHub はこれらのクロスワークスペースフィールドをサポートしません。
通常のログクエリでは、warnings に DQLDataAccessScopeRestricted が返される場合があります。details[].metadata.namespace は logging で、restriction=partial は権限のあるインデックスのみが返されることを示し、all は関連するログインデックスに権限がなく空の結果が返されることを示します。HTTP 200 の空データを、ワークスペース全体にデータがないとみなしてはいけません。未復旧イベントクエリ を参照してください。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/df/asynchronous/query_data' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"queries":[{"qtype":"dql","async_timeout":"5s","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 | まだ実行中かどうか。true の場合のみポーリングを継続します。false の場合は停止し、async_id が非空でも停止します。 |
| 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 | ワークスペース宣言。 |
| content.data[].query_status | string | QueryHub では pending、running、success、failed です。一部の通常成功レスポンスにはこのフィールドがありません。 |
| content.data[].query_error.message | string | QueryHub 単一項目のエラーメッセージ。 |
| content.data[].series[].columnTypes | array<string> |
QueryHub の列型で、columns と 1 対 1 に対応します。 |
| content.data[].uuid | string または null | QueryHub クエリ項目のクライアント識別子。 |
| content.data[].truncated | boolean | QueryHub の成功結果が切り詰められたかどうか。 |
| content | object | 順序付きのバッチ結果オブジェクト。 |
| content.data[].async_id | string | まだ実行中の項目のタスク ID です。QueryHub の終端状態ではクリアされ、通常の失敗項目では非空 ID が保持される場合があります。is_running とエラーフィールドで継続可否を判断します。 |
| content.data[].query_error.errorSource | string | 通常の外部クエリのエラー発生元: studio、transport、func、datasource または unknown。 |
| content.data[].query_error.errorStage | string | 通常の外部クエリの失敗段階。 |
| content.data[].query_error.taskId | string | 診断用の元タスク ID。終端状態でも保持される場合があります。 |
| content.data[].query_error.upstreamTraceId | string | 上流が提供するトレース ID。省略される場合があります。 |
| content.data[].query_error.redacted | boolean | 診断情報で機密値のマスキングが行われたかどうか。省略される場合があります。 |
| content.data[].query_error.errorDetails | object | 公開可能なエラー診断スカラー。 |
| content.data[].errorInfo | object | 一部の通常外部クエリで保持される互換エラーオブジェクト。message は query_error.error に対応し、その他の診断フィールドも同様です。 |
| content.data[].warnings[].code | string | クエリ警告コードです。HTTP 200 でも返される場合があります。 |
| content.data[].warnings[].message | string | ローカライズされた警告メッセージ。 |
| content.data[].warnings[].details | JSON 値 | エンジンが提供する追加情報です。実際のレスポンスに従って読み取ります。 |
| content.data[].queryTimeRangeAdjusted | object | 通常のログ長期保存ルールによってクエリ範囲が調整された場合に現れます。 |
| content.data[].queryTimeRangeAdjusted.adjusted | boolean | 調整マーカーで、出現時は true です。 |
| content.data[].queryTimeRangeAdjusted.reason | string | 現在は log_long_storage_policy です。 |
| content.data[].queryTimeRangeAdjusted.originalTimeRange | array | 元のクエリ時間範囲です。 |
| content.data[].queryTimeRangeAdjusted.queryTimeRange | array | 実際のクエリ範囲です。空配列はクエリ可能なデータがないことを示します。 |
| content.data[].queryTimeRangeAdjusted.mode | string | standard_window、long_storage_day または empty です。 |
| content.data[].queryTimeRangeAdjusted.standardDuration | string | 標準保存期間で、日単位です。 |
| content.data[].queryTimeRangeAdjusted.retentionDuration | string | 全体の保持期間で、日単位です。 |
| content.data[].series[].values[] | array | columns と 1 対 1 に対応する単一行で、セルは JSON 値または null です。QueryHub の大きな整数は精度損失を避けるため文字列になる場合があります。 |
| content.data[].series[].values[][] | JSON 値 | ある列のセル値で、型は列説明および元データと一致します。 |
| content.data[].series[].value_desc | object | 一部の通常 SHOW_FIELD クエリで fieldTagDescNeeded=true の場合にフィールドメタ情報を提供します。 |
| content.data[].series[].value_desc.字段名 | object | フィールドの型、単位、説明。 |
| content.data[].series[].value_desc.字段名.name | string | フィールド名。 |
| content.data[].series[].value_desc.字段名.type | string | フィールド型。 |
| content.data[].series[].value_desc.字段名.unit | string | 単位です。設定がない場合は空になることがあります。 |
| content.data[].series[].value_desc.字段名.desc | string | フィールドの説明です。設定がない場合は空になることがあります。 |
| content.data[].query_error.errorDetails.message | JSON スカラー | 任意の診断フィールドで、実際のレスポンスに従って提供されます。診断状態を今回の HTTP ステータスとみなさないでください。 |
| content.data[].query_error.errorDetails.reason | string | 通常のネイティブクエリのバインド失敗時には resubmit_required になる場合があり、新しいクエリを作成する必要があり、古い ID をポーリングできません。 |
| content.data[].query_error.errorDetails.error | JSON スカラー | 任意の診断フィールドで、実際のレスポンスに従って提供されます。診断状態を今回の HTTP ステータスとみなさないでください。 |
| content.data[].query_error.errorDetails.status | JSON スカラー | 任意の診断フィールドで、実際のレスポンスに従って提供されます。診断状態を今回の HTTP ステータスとみなさないでください。 |
| content.data[].query_error.errorDetails.taskStatus | JSON スカラー | 任意の診断フィールドで、実際のレスポンスに従って提供されます。診断状態を今回の HTTP ステータスとみなさないでください。 |
| content.data[].query_error.errorDetails.exceptionType | JSON スカラー | 任意の診断フィールドで、実際のレスポンスに従って提供されます。診断状態を今回の HTTP ステータスとみなさないでください。 |
| content.data[].query_error.errorDetails.exception | JSON スカラー | 任意の診断フィールドで、実際のレスポンスに従って提供されます。診断状態を今回の HTTP ステータスとみなさないでください。 |
| content.data[].errorInfo.errorType | JSON スカラー | 任意の診断フィールドで、実際のレスポンスに従って提供されます。診断状態を今回の HTTP ステータスとみなさないでください。 |
| content.data[].errorInfo.errorCode | JSON スカラー | 任意の診断フィールドで、実際のレスポンスに従って提供されます。診断状態を今回の HTTP ステータスとみなさないでください。 |
| content.data[].errorInfo.message | JSON スカラー | 任意の診断フィールドで、実際のレスポンスに従って提供されます。診断状態を今回の HTTP ステータスとみなさないでください。 |
| content.data[].errorInfo.errorSource | JSON スカラー | 任意の診断フィールドで、実際のレスポンスに従って提供されます。診断状態を今回の HTTP ステータスとみなさないでください。 |
| content.data[].errorInfo.errorStage | JSON スカラー | 任意の診断フィールドで、実際のレスポンスに従って提供されます。診断状態を今回の HTTP ステータスとみなさないでください。 |
| content.data[].errorInfo.taskId | JSON スカラー | 任意の診断フィールドで、実際のレスポンスに従って提供されます。診断状態を今回の HTTP ステータスとみなさないでください。 |
| content.data[].errorInfo.upstreamTraceId | JSON スカラー | 任意の診断フィールドで、実際のレスポンスに従って提供されます。診断状態を今回の HTTP ステータスとみなさないでください。 |
| content.data[].errorInfo.redacted | JSON スカラー | 任意の診断フィールドで、実際のレスポンスに従って提供されます。診断状態を今回の HTTP ステータスとみなさないでください。 |
| content.data[].errorInfo.errorDetails | object | 任意の診断フィールドで、実際のレスポンスに従って提供されます。診断状態を今回の HTTP ステータスとみなさないでください。 |
| レスポンスヘッダー | 型 | 説明 |
|---|---|---|
| Content-Type | string | application/json。 |
| Cache-Control | string | QueryHub 自体の成功応答および捕捉された QueryHubError 応答は no-store です。混在バッチで通常クエリがその他の例外をスローした場合、このヘッダーは保証されません。純粋な通常非同期入口には同期 v1 の追加 ETag 設定がないため、同じキャッシュヘッダーに依存すべきではありません。 |
{
"code": 200,
"content": {
"data": [
{
"async_id": "legacy-task-from-response",
"is_running": true,
"series": []
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
通常タスクのポーリング
curl --request POST '<Endpoint>/api/v1/df/asynchronous/query_data' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"queries":[{"qtype":"dql","async_timeout":"5s","query":{"q":"M::`cpu`:(`usage_idle`)","timeRange":[1785427200000,1785430800000],"limit":5},"async_id":"legacy-task-from-response"}]}'
QueryHub 初回送信
curl --request POST '<Endpoint>/api/v1/df/asynchronous/query_data' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"queries":[{"uuid":"db-query","qtype":"queryhub","query":{"datasourceId":"orders","mode":"native","native":{"language":"sql","statement":"SELECT 1 AS value","parameters":[]}}}]}'
QueryHub 送信レスポンス
{
"code": 200,
"content": {
"data": [
{
"uuid": "db-query",
"async_id": "qhtask_00000000000000000000000000000001",
"query_status": "pending",
"is_running": true,
"series": []
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
QueryHub ポーリング(同じ API Key を使用)
curl --request POST '<Endpoint>/api/v1/df/asynchronous/query_data' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"queries":[{"uuid":"db-query","qtype":"queryhub","async_id":"qhtask_00000000000000000000000000000001"}]}'
QueryHub 完了レスポンス
{
"code": 200,
"content": {
"data": [
{
"uuid": "db-query",
"async_id": "",
"query_status": "success",
"is_running": false,
"truncated": false,
"series": [
{
"columns": [
"value"
],
"columnTypes": [
"Int64"
],
"values": [
[
1
]
]
}
]
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
QueryHub タスクが存在しないか期限切れの場合の単一項目失敗
{
"code": 200,
"content": {
"data": [
{
"uuid": "db-query",
"async_id": "",
"query_status": "failed",
"is_running": false,
"series": [],
"query_error": {
"errorCode": "QueryHubTaskNotFound",
"message": "查询任务已失效,请重新提交。"
}
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
通常 GET 呼び出し
curl --get '<Endpoint>/api/v1/df/asynchronous/query_data' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode 'body={"queries":[{"qtype":"dql","async_timeout":"5s","query":{"q":"M::`cpu`:(`usage_idle`)","timeRange":[1785427200000,1785430800000],"limit":5}}]}'
エラーレスポンス¶
認証、レート制限、共通リクエストエラーの詳細は 共通エラー定義 を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンス説明 | 対応方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストパラメータがフィールド宣言に違反 | メッセージに無効なフィールドまたはルールが示されます。 | 対応するパラメータ表に従ってリクエストを修正します。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文エラー | リクエスト JSON の形式エラー。content に reason、line、column が含まれます。 | JSON 構文を修正して再試行します。 |
| 400 | ft.TimeRangeUnitMismatch | timeRange の開始と終了で異なる単位を使用 | 開始時刻と終了時刻の単位が一致していません。 | 同じ精度のタイムスタンプに統一します。 |
| 403 | ft.ForbiddenQuery | API Key に対象データのクエリ権限がない、または対象サイトが権限エラーでクロスサイトクエリを拒否 | DQL クエリ権限がありません。 | 対象ワークスペースの認可と対象サイトを確認します。 |
| 403 | forethought.QueryHubForbidden | QueryHub 全体の呼び出し ID、ワークスペース、またはクエリ権限が許可されていない | 現在の ID にはその QueryHub 操作を実行する権限がありません。 | 同じワークスペースの元の API Key を使用し、サイト/データソース権限を確認します。対象ワークスペースヘッダーやオフライン ID は使用しないでください。 |
| 400 | ft.JsonFormatError | 通常クエリオブジェクトまたは queries/query 構造が想定 JSON 型でない | 一部の json ファイル形式エラー | queries 配列を送信し、各項目の query をオブジェクトにします。 |
| 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 と実際の状態に応じてバックオフして再試行します。 |
| 400 | forethought.QueryHubInvalidFields | QueryHub バッチ構造エラー、GET/非 JSON/URL body、または 1~20 項目でない配列 | メッセージが空の場合があります。 | 本ページの POST JSON テンプレートを使用し、トップレベルの query や通常 GET の body を混在させないでください。 |
| 503 | forethought.QueryHubUnavailable | QueryHub 機能が無効、またはサービスが利用不可 | クエリサービスまたはデータソースが一時的に利用できません。 | 権限、クエリ機能、サービス状態を確認します。 |
| 400 | ft.QueryActionLimit | サイトのスロークエリ保護が現在の Key を一時的に制限 | スロークエリが多すぎるため、短時間リクエストが制限されています | 制限解除を待ち、超大規模クエリを減らし、連続リトライを避けます。 |
| 406 | ft.IllegalDensity | density が現在のサイトで許可されたポイント密度設定にない | density が不正です。選択可能な値: {} | interval または maxPointCount を明確に指定することを優先し、density 使用前にサイト設定を確認します。 |
| 403 | ft.Forbidden | 本 OpenAPI で公開されていないホスト型外部データソースクエリチャネルを使用 | 操作権限がありません | 認可済みの QueryHub プロトコルまたはサイトが明確にサポートするクエリ方式を使用し、Front リクエストをそのまま流用しないでください。 |
| 500 | ft.InternalServerError | 制御されていないクエリ接続、パラメータ構造、または内部サービス例外 | 内部エラー | traceId とマスキング済みリクエストを保持します。送信タイムアウト時はタスクが生成済みか先に確認し、重複送信を避けます。 |
| 502 | forethought.QueryHubInvalidBatch | 混在バッチの通常クエリ結果数がリクエスト数と一致しない | メッセージが空の場合があります。 | 通常クエリと QueryHub バッチを分けて確認し、traceId を保持します。 |
| 200 | QueryHubInvalidId | QueryHub 単一項目失敗。コードは content.data[].query_error.errorCode にあり、外側は success=true のままの場合があります | 単一項目の message は空、または汎用のクエリ失敗メッセージの場合があります。 | 終端項目のポーリングを停止します。欠落/期限切れタスクは元のリクエストで再送信します。ビジー/利用不可はバックオフし、権限/モード/バージョン問題は設定を先に修正します。 |
| 200 | QueryHubInvalidFields | QueryHub 単一項目失敗。コードは content.data[].query_error.errorCode にあり、外側は success=true のままの場合があります | データソース設定フィールドと入力形式を確認してください。 | 終端項目のポーリングを停止します。欠落/期限切れタスクは元のリクエストで再送信します。ビジー/利用不可はバックオフし、権限/モード/バージョン問題は設定を先に修正します。 |
| 200 | QueryHubUnsupportedMode | QueryHub 単一項目失敗。コードは content.data[].query_error.errorCode にあり、外側は success=true のままの場合があります | 単一項目の message は空、または汎用のクエリ失敗メッセージの場合があります。 | 終端項目のポーリングを停止します。欠落/期限切れタスクは元のリクエストで再送信します。ビジー/利用不可はバックオフし、権限/モード/バージョン問題は設定を先に修正します。 |
| 200 | QueryHubUnsupportedContract | QueryHub 単一項目失敗。コードは content.data[].query_error.errorCode にあり、外側は success=true のままの場合があります | 単一項目の message は空、または汎用のクエリ失敗メッセージの場合があります。 | 終端項目のポーリングを停止します。欠落/期限切れタスクは元のリクエストで再送信します。ビジー/利用不可はバックオフし、権限/モード/バージョン問題は設定を先に修正します。 |
| 200 | QueryHubForbidden | QueryHub 単一項目失敗。コードは content.data[].query_error.errorCode にあり、外側は success=true のままの場合があります | クエリ権限がありません。 | 終端項目のポーリングを停止します。欠落/期限切れタスクは元のリクエストで再送信します。ビジー/利用不可はバックオフし、権限/モード/バージョン問題は設定を先に修正します。 |
| 200 | QueryHubDatasourceNotFound | QueryHub 単一項目失敗。コードは content.data[].query_error.errorCode にあり、外側は success=true のままの場合があります | 単一項目の message は空、または汎用のクエリ失敗メッセージの場合があります。 | 終端項目のポーリングを停止します。欠落/期限切れタスクは元のリクエストで再送信します。ビジー/利用不可はバックオフし、権限/モード/バージョン問題は設定を先に修正します。 |
| 200 | QueryHubRevisionConflict | QueryHub 単一項目失敗。コードは content.data[].query_error.errorCode にあり、外側は success=true のままの場合があります | 単一項目の message は空、または汎用のクエリ失敗メッセージの場合があります。 | 終端項目のポーリングを停止します。欠落/期限切れタスクは元のリクエストで再送信します。ビジー/利用不可はバックオフし、権限/モード/バージョン問題は設定を先に修正します。 |
| 200 | QueryHubSnapshotNotReady | QueryHub 単一項目失敗。コードは content.data[].query_error.errorCode にあり、外側は success=true のままの場合があります | データソース設定がまだ有効になっていません。しばらくしてから再試行してください。 | 終端項目のポーリングを停止します。欠落/期限切れタスクは元のリクエストで再送信します。ビジー/利用不可はバックオフし、権限/モード/バージョン問題は設定を先に修正します。 |
| 200 | QueryHubQueryRejected | QueryHub 単一項目失敗。コードは content.data[].query_error.errorCode にあり、外側は success=true のままの場合があります | クエリの実行に失敗しました。クエリ条件とデータソース設定を確認してください。 | 終端項目のポーリングを停止します。欠落/期限切れタスクは元のリクエストで再送信します。ビジー/利用不可はバックオフし、権限/モード/バージョン問題は設定を先に修正します。 |
| 200 | QueryHubQueryTimeout | QueryHub 単一項目失敗。コードは content.data[].query_error.errorCode にあり、外側は success=true のままの場合があります | クエリがタイムアウトしました。 | 終端項目のポーリングを停止します。欠落/期限切れタスクは元のリクエストで再送信します。ビジー/利用不可はバックオフし、権限/モード/バージョン問題は設定を先に修正します。 |
| 200 | QueryHubInvalidResult | QueryHub 単一項目失敗。コードは content.data[].query_error.errorCode にあり、外側は success=true のままの場合があります | クエリ結果の形式が異常です。 | 終端項目のポーリングを停止します。欠落/期限切れタスクは元のリクエストで再送信します。ビジー/利用不可はバックオフし、権限/モード/バージョン問題は設定を先に修正します。 |
| 200 | QueryHubUnavailable | QueryHub 単一項目失敗。コードは content.data[].query_error.errorCode にあり、外側は success=true のままの場合があります | クエリサービスまたはデータソースが一時的に利用できません。 | 終端項目のポーリングを停止します。欠落/期限切れタスクは元のリクエストで再送信します。ビジー/利用不可はバックオフし、権限/モード/バージョン問題は設定を先に修正します。 |
| 200 | QueryHubBusy | QueryHub 単一項目失敗。コードは content.data[].query_error.errorCode にあり、外側は success=true のままの場合があります | クエリがビジーです。しばらくしてから再試行してください。 | 終端項目のポーリングを停止します。欠落/期限切れタスクは元のリクエストで再送信します。ビジー/利用不可はバックオフし、権限/モード/バージョン問題は設定を先に修正します。 |
| 200 | QueryHubTaskNotFound | QueryHub 単一項目失敗。コードは content.data[].query_error.errorCode にあり、外側は success=true のままの場合があります | クエリタスクは無効になりました。再送信してください。 | 終端項目のポーリングを停止します。欠落/期限切れタスクは元のリクエストで再送信します。ビジー/利用不可はバックオフし、権限/モード/バージョン問題は設定を先に修正します。 |
| 200 | QueryHubTaskCancelled | QueryHub 単一項目失敗。コードは content.data[].query_error.errorCode にあり、外側は success=true のままの場合があります | クエリタスクはキャンセルされました。 | 終端項目のポーリングを停止します。欠落/期限切れタスクは元のリクエストで再送信します。ビジー/利用不可はバックオフし、権限/モード/バージョン問題は設定を先に修正します。 |
| 200 | QueryResultUnavailable | 通常クエリの単一項目で query_error/errorInfo が失敗。外側は成功のままの場合があります | その項目の error/message/reason の実際のテキストに従います。 | is_running=false になった時点でポーリングを停止します。キャッシュまたはバインディングが無効な場合は、まずデータソース/クライアント状態を確認し、新しいクエリを再送信します。古い async_id を再試行しないでください。 |
| 200 | InvalidQueryResponse | 通常クエリの単一項目で query_error/errorInfo が失敗。外側は成功のままの場合があります | その項目の error/message/reason の実際のテキストに従います。 | is_running=false になった時点でポーリングを停止します。キャッシュまたはバインディングが無効な場合は、まずデータソース/クライアント状態を確認し、新しいクエリを再送信します。古い async_id を再試行しないでください。 |
| 200 | NoFuncClient | 通常クエリの単一項目で query_error/errorInfo が失敗。外側は成功のままの場合があります | その項目の error/message/reason の実際のテキストに従います。 | is_running=false になった時点でポーリングを停止します。キャッシュまたはバインディングが無効な場合は、まずデータソース/クライアント状態を確認し、新しいクエリを再送信します。古い async_id を再試行しないでください。 |
| 200 | FuncWorkerNoResponse | 通常クエリの単一項目で query_error/errorInfo が失敗。外側は成功のままの場合があります | その項目の error/message/reason の実際のテキストに従います。 | is_running=false になった時点でポーリングを停止します。キャッシュまたはバインディングが無効な場合は、まずデータソース/クライアント状態を確認し、新しいクエリを再送信します。古い async_id を再試行しないでください。 |
| 200 | ExternalQueryTimeout | 通常クエリの単一項目で query_error/errorInfo が失敗。外側は成功のままの場合があります | その項目の error/message/reason の実際のテキストに従います。 | is_running=false になった時点でポーリングを停止します。キャッシュまたはバインディングが無効な場合は、まずデータソース/クライアント状態を確認し、新しいクエリを再送信します。古い async_id を再試行しないでください。 |
| 200 | ExternalQueryExecutionFailed | 通常クエリの単一項目で query_error/errorInfo が失敗。外側は成功のままの場合があります | その項目の error/message/reason の実際のテキストに従います。 | is_running=false になった時点でポーリングを停止します。キャッシュまたはバインディングが無効な場合は、まずデータソース/クライアント状態を確認し、新しいクエリを再送信します。古い async_id を再試行しないでください。 |
| 200 | ExternalQueryBindingUnavailable | 通常クエリの単一項目で query_error/errorInfo が失敗。外側は成功のままの場合があります | その項目の error/message/reason の実際のテキストに従います。 | is_running=false になった時点でポーリングを停止します。キャッシュまたはバインディングが無効な場合は、まずデータソース/クライアント状態を確認し、新しいクエリを再送信します。古い async_id を再試行しないでください。 |
| 200 | WebSocketDispatchFailed | 通常クエリの単一項目で query_error/errorInfo が失敗。外側は成功のままの場合があります | その項目の error/message/reason の実際のテキストに従います。 | is_running=false になった時点でポーリングを停止します。キャッシュまたはバインディングが無効な場合は、まずデータソース/クライアント状態を確認し、新しいクエリを再送信します。古い async_id を再試行しないでください。 |
| 200 | DQLAsyncQueryBindingUnavailable | 通常クエリの単一項目で query_error/errorInfo が失敗。外側は成功のままの場合があります | その項目の error/message/reason の実際のテキストに従います。 | is_running=false になった時点でポーリングを停止します。キャッシュまたはバインディングが無効な場合は、まずデータソース/クライアント状態を確認し、新しいクエリを再送信します。古い async_id を再試行しないでください。 |
| 422 | ft.KodoAggregateOutputRowsLimitReached | 集計中間結果の推定行数が制限を超えている | 集計中間結果が少なくとも {} 行を生成すると推定され、{} 行の上限を超えています。時間範囲を縮小するか、フィルタ条件を追加するか、グループ化を減らしてください。返却件数を減らすだけではこの制限を回避できません。 | 時間範囲を縮小し、フィルタを追加するかグループ化を減らします。limit を減らすだけでは集計中間結果が減らない場合があります。 |
| 422 | ft.KodoScanRowLimitExceeded | 単一実行段階のスキャン行数が上限超過 | クエリの単一実行段階で {} 行を処理すると推定され、{} 行の上限を超えています。時間範囲を縮小するかサンプリング比率を下げてください。 | 時間範囲を縮小し、選択性の高いフィルタを追加するかサンプリング範囲を減らします。 |
| 422 | ft.KodoScanBytesLimitExceeded | スキャン時の展開後バイト数が制限超過 | クエリの単一実行段階で {} バイト(非圧縮)をスキャンすると推定され、{} バイトの上限を超えています。時間範囲を縮小するかサンプリング比率を下げてください。 | スキャン時間とインデックス範囲を縮小し、返却件数を減らすだけにしないでください。 |
| 422 | ft.KodoQueryEstimateLimitExceeded | アイドルクラスタでの推定クエリ時間が制限に達した | アイドルクラスタでのクエリ推定時間は {} 秒で、{} 秒の制限に達しており、{} 行のデータが関係します。時間範囲を縮小するかクエリを簡素化してください。 | クエリを簡素化するか範囲を縮小してから再送信し、元の大規模クエリを連続して再試行しないでください。 |
| 429 | ft.KodoServerOverloaded | クエリサービスが過負荷、またはリクエストが頻繁すぎる | 現在のリクエストが頻繁すぎます。しばらくしてから再試行してください。 | バックオフし、同時実行数を下げてから再試行します。 |
| 429 | ft.KodoQueryQueueAdmissionFailed | クエリアドミッションのキューイング失敗 | クエリアドミッションキューがリクエスト処理に失敗しました。しばらくしてから再試行してください。 | バックオフし、同時実行数を減らします。 |
| 429 | ft.KodoUserDQLRateLimited | 頻繁な超大規模クエリが一時制限を引き起こした | 超大量データのクエリを頻繁に実行したため、クエリが一時的に制限されています。{} 分後に再試行してください | メッセージに示された制限期間が終了するのを待ち、クエリ範囲を縮小してから再試行します。 |
| 406 | ft.KodoOffsetWithCursorTime | offset と cursor_time を同時に使用 | オフセット(offset)パラメータとカーソル時間(cursor_time)パラメータは同時に使用できません | オフセットページングまたはカーソルページングのいずれかを選択し、2 つの制御項目を同時に送信しないでください。 |
| 406 | ft.KodoQueryNotFound | 通常クエリタスクが存在しないか期限切れ | クエリが存在しないか期限切れです | 古い ID のポーリングを停止し、結果を取得する必要がないことを確認したうえで元のパラメータで新しいクエリを作成します。 |
| 406 | ft.KodoRequestDeadlineExceeded | クエリがバックエンドの実行期限を超過 | データクエリがタイムアウトしました。原因として、データ量が多すぎる、ネットワーク遅延、サーバー負荷が高すぎることが考えられます。次の方法で解決できます: 1. フィルタ条件を追加するか時間範囲を縮小してから再度クエリを実行します。 2. しばらく待ってから再度クエリを試行します。 |
時間範囲、グループ化、スキャンデータ量を縮小して再送信します。 |
| 406 | ft.KodoTooManyRows | クエリデータ量が上限超過 | クエリのデータ量が最大数量制限を超えています。フィルタ条件を追加するか時間範囲を縮小してから再度クエリを実行してください。 | フィルタを追加するか時間範囲を縮小します。 |