コンテンツにスキップ

DQL データクエリ



POST /api/v1/df/query_data_v1
GET /api/v1/df/query_data_v1

概要

クエリバッチ単位で DQL または PromQL のデータを取得します。POST では QueryHub データソースによるクエリもサポートします。

呼び出し前の準備と使用手順

通常の DQL または PromQL では POST JSON を推奨します。GET では同じ JSON オブジェクトを URL エンコードした body に格納します。QueryHub は POST JSON のみを使用し、現在のワークスペースでそのクエリ言語をサポートするデータソースを有効にする必要があります。同期の混在バッチは最大 20 項目、うち QueryHub クエリは最大 1 件です。複数の QueryHub クエリが必要な場合は、非同期クエリを使用してください。

例に含まれるメジャーメントとフィールドは、ワークスペースで収集済みのデータに置き換える必要があります。これらはメジャーメント一覧およびメジャーメントスキーマから取得できます。時間範囲はデータが存在する期間に置き換えてください。レスポンスを解析する際は、項目ごとに warnings または query_error を確認し、ページ継続時はその項目自身のカーソルを使用します。

リクエストヘッダー

パラメータ名 型 必須 説明
DF-API-KEY string Y 現在のワークスペースの OpenAPI Key。
例: <DF-API-KEY>
取得・入力方法: 対象ワークスペースの API Key 管理で、クエリ権限を持つ認証情報を取得します。

Query リクエストパラメータ

パラメータ名 型 必須 説明
body string GET クエリで使用する完全な JSON オブジェクト文字列。省略し、かつ他のクエリを送信しない場合は空の結果を返します。
例: {"queries":[{"qtype":"dql","query":{"q":"M::`cpu`:(`usage_idle`)","timeRange":[1785427200000,1785430800000],"limit":5}}]}
取得・入力方法: クエリオブジェクトを一度シリアライズしてから URL エンコードします(例: curl --data-urlencode)。

Body リクエストパラメータ

パラメータ名 型 必須 説明
queries array 業務クエリは少なくとも 1 項目を送信します。省略または空配列の場合は空のデータを返します。
null 許可: False
例: [{"qtype": "dql", "query": {"q": "M::`cpu`:(`usage_idle`)", "timeRange": [1785427200000, 1785430800000], "limit": 5}}]
取得・入力方法: 通常クエリおよび QueryHub の例を参考にクエリ項目を構築します。qtype がクエリタイプを決定します。
fieldTagDescNeeded boolean デフォルトは false。
null 許可: False
例: false
取得・入力方法: フィールドまたは Tag の説明も併せて取得する場合は true を指定します。

パラメータの補足説明

QueryHub は POST JSON でのみ送信します。queries[].qtype には queryhub を、query には datasourceId、mode、および同名の native または dql オブジェクトを指定します。 API Key の routine.defaultAccess および現在のワークスペースのインスタンスクエリ権限が必要です。同期バッチでは QueryHub クエリは最大 1 件です。 項目単位のエラーは content.data[].query_error に格納され、成功時は series と truncated を返します。

クエリの説明


本インターフェースは POST と GET の両方をサポートし、どちらの方式も同じ JSON object パラメータ構造を使用します:

  • POST:完全なパラメータを application/json のリクエストボディとして送信します。
  • GET:HTTP エンティティボディを使用せず、クエリ文字列で body=<完全な JSON object 文字列> として送信します。 クライアントは body パラメータを URL エンコードする必要があります。
  • トップレベルは JSON object である必要があり、二重に JSON エンコードされた string、array、null、number、boolean は受け付けません。

レスポンスの 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 と共存します。

オプションパラメータのデフォルト値は、「呼び出し元がそのパラメータを省略した」場合の動作を示します:

  • query.timeRange を指定しない場合、Studio は下流に time_range: [] を渡し、Studio 側で固定の時間ウィンドウを補完せず、DQL 文内の時間範囲も上書きしません。現在、通常の DQL Select のメイン経路では GuanceDB v1.52.0 がフォールバックとして直近 30 分をクエリします。この値は下流の実装に属するものであり、すべての qtype やすべてのストレージエンジンに共通する OpenAPI のデフォルト値ではありません。PromQL クエリでは 2 つの時刻を明示的に指定する必要があります。バージョンやエンジンをまたいで一貫した動作を確保するには、[startTimeMs, endTimeMs] の 2 つのミリ秒タイムスタンプを明示的に渡すことを推奨します。
  • query.limit、query.slimit、並べ替え、最大ポイント数、クエリ時間の上限は、DQL 文、下流サービスの設定、ストレージエンジンの影響を受け、OpenAPI として統一された固定デフォルト値はありません。呼び出し元が安定した境界を必要とする場合は明示的に指定してください。

クロスワークスペース/クロスサイトクエリの制約:

  • 1 つのリクエスト内のすべての queries[*] は同じ targetRegion しか指せません。複数のサイトをクエリする必要がある場合は、サイトごとにリクエストを分割し、クライアント側で結果をマージしてください。
  • 空でない workspaceUUIDs は workspaceUUID より優先されます。workspaceUUIDs が空配列または null の場合は workspaceUUID にフォールバックします。両方のフィールドを同時に指定しないことを推奨します。現在のワークスペースをクエリする場合は両方とも省略できます。権限を付与されたワークスペースを明示的にクエリする場合は、そのワークスペースが属する targetRegion も併せて指定することを推奨します。
  • workspaceUUIDs=["*"] の場合は targetRegion を指定できます。指定しない場合は現在のサイトで権限を付与されたワークスペースと現在のワークスペースをクエリします。互換表記の workspaceUUID="*" も引き続きサポートされ、同じ規則に従います。
  • 対象のワークスペースと targetRegion は /api/v1/wksp_share/granted_ws_list から取得してください。完全な例は次を参照してください:OpenAPI クロスサイトデータクエリ。

  • パラメータ説明

パラメータ名 type 必須 デフォルト値 / 省略時の動作 説明
queries array [](空のデータを返す) 複数コマンドクエリ。内容は query オブジェクトからなるリストです。業務クエリでは少なくとも 1 つの query を渡す必要があります
fieldTagDescNeeded boolean false field または tag の説明情報が必要かどうか
  1. queries[*] のメンバーパラメータ構造の説明
パラメータ名 type 必須 デフォルト値 / 省略時の動作 説明
qtype string dql クエリ文のタイプ
dql: DQL タイプのクエリ文を示します;
promql: PromQL タイプのクエリ文を示します。例 dql。
query json Y - 有効なクエリには必須です。欠落している場合や query.q が空の場合は、有効な下流クエリになりません。例 {"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 はキャッシュを使用することを示します。例 false。
query.disable_streaming_aggregation boolean false ストリーミング集約を無効にするかどうか。明示的に true を渡すと無効化され、明示的に false を渡すと使用が許可されます。例 false。
query.promqlType enum rangeQuery qtype=promql の場合に有効です。選択可能な値は instantQuery、rangeQuery です。例 rangeQuery。
query.highlight boolean false ハイライトデータを表示するかどうか。例 false。
query.timeRange array [] 外部時間範囲。DQL で指定しない場合は文内のウィンドウを上書きせず、現在の通常 Select のメイン経路では GuanceDB がフォールバックとして直近 30 分をクエリします。PromQL では 2 つの時刻を明示的に指定する必要があり、他のエンジンでは動作が異なる場合があります。DQL / PromQL の開始時刻と終了時刻は同じ単位(秒、ミリ秒、マイクロ秒、ナノ秒)を使用する必要があり、混在させた場合は HTTP 400 ft.TimeRangeUnitMismatch を返します。ページングカーソルは独立して保持されます。例 [1785427200000,1785430800000]。必要なクエリウィンドウを同じ精度の 2 つのタイムスタンプに置き換えてください。Unix ミリ秒を推奨します。
query.disableMultipleField bool true 単一列モードを有効にするかどうか。例 true。
query.showLabel bool false オブジェクトの labels を表示するかどうか。例 false。
query.funcList array [] DQL の戻り値を再度集約して修飾します。選択した集約関数に従って処理されます。例 ["last"]。
query.slimit integer DQL / 下流設定による 時系列のグループサイズ。メトリクスクエリにのみ有効です。例 10。
query.soffset integer DQL の値;DQL でも未設定の場合は追加オフセットなし 時系列のグループオフセット。現在のパーサーは、DQL で設定されていないオフセットを正の外部値でのみ補完し、0 は DQL に既存の値をクリアしません。例 10。
query.limit integer DQL / 下流設定による ページサイズ。例 5。
query.offset integer DQL の値;DQL でも未設定の場合は追加オフセットなし ページングオフセット。現在のパーサーは、DQL で設定されていないオフセットを正の外部値でのみ補完し、0 は DQL に既存の値をクリアしません。例 5。
query.orderby array DQL / クエリエンジンによる 並べ替えリスト。構造は {fieldName: method} です。メジャーメントクエリでは fieldName=time のみをサポートし、method は desc、asc を選択できます。例 [{"time":"desc"}]。
query.sorderby array DQL / クエリエンジンによる 並べ替えリスト。column は単一の値を返す集約関数をサポートします(例: min、max、last、avg、p90、p95、count)。
query.order_by array DQL / クエリエンジンによる Doris エンジン互換の並べ替えリスト。構造は [{"column": "field", "order": "DESC"}] です。例 [{"column":"time","order":"DESC"}]。
query.sorder_by array DQL / クエリエンジンによる Doris エンジン互換の時系列並べ替えリスト。構造は [{"column": "field", "order": "DESC"}] です。例 [{"column":"usage_idle","order":"DESC"}]。
query.density string DQL / クエリエンジンによる レスポンスのポイント密度。DQL 文内の制御パラメータより優先されます。例 medium。
query.interval number DQL / クエリエンジンによる 時間スライスの間隔。Kodo の int64 範囲に変換可能で、かつ 1ms 以上の整数のみ受け付けます。単位は interval_unit で指定します。例 60。
query.interval_unit string s interval の単位。s、ms を選択できます。例 s。
query.align_time boolean false クエリエンジンの時間グリッドに時間スライスを整列するかどうか。例 false。
query.tz string Asia/Shanghai クエリのタイムゾーン。例 Asia/Shanghai。
query.search_after array ページングマーカーを設定しない ディープページングパラメータ。次のリクエストでは前回のレスポンスの search_after を渡す必要があります。例 [1785427200000,"cursor-example"]。ページ継続時は、前回の同じクエリが実際に返した配列をコピーする必要があります。
query.maxPointCount integer DQL / クエリエンジンによる 最大ポイント数。例 360。
query.workspaceUUID string 現在のワークスペース クエリ対象の単一の権限付与元ワークスペース UUID。* は targetRegion 内のすべての権限付与済みワークスペースをクエリすることを示します。例 wksp_example。
query.workspaceUUIDs array 設定しない クエリ対象の権限付与元ワークスペース UUID のリスト。空でない場合は query.workspaceUUID より優先されます。同じリストは同じサイトに属する必要があります。["*"] は targetRegion 内のすべての権限付与済みワークスペースをクエリすることを示します。両方のフィールドを同時に指定しないことを推奨します。例 ["wksp_example"]。
query.targetRegion string 現在のワークスペースのクエリでは現在のサイトが暗黙的に使用され、ワイルドカード時はデフォルトで現在のサイト 権限付与元ワークスペースが属するサイトの regionCode。/wksp_share/granted_ws_list 内で対象の workspaceUUID と同じグループの regionCode から取得します。明示的なクロスサイトクエリでは指定を推奨します。ワイルドカード指定かつ省略時は現在のサイトを使用します。互換表記の workspaceUUID="*" も同じ規則に従います。例 example-region。
query.output_format string 既存の JSON レスポンス形式 lineprotocol を設定すると、項目単位のクエリ内容は行プロトコルを使用でき、外側のレスポンスは引き続き JSON です。例 lineprotocol。
query.cursor_time integer カーソルを設定しない 最初の分割クエリでは end_time を設定します。以降はレスポンスの next_cursor_time を渡します。例 1785430800000。ページ継続時はレスポンスの next_cursor_time を使用します。
query.cursor_token string トークンを設定しない ページング時に前回のレスポンスの next_cursor_token を渡します。渡さない場合、同じタイムスタンプのデータがページ切り替え時にスキップされる可能性があります。例 cursor-example。ページ継続時はレスポンスの next_cursor_token を使用します。
query.disable_sampling bool false サンプリングを無効にするかどうか。例 false。
query.disable_truncate bool false 返却内容の切り捨てを無効にするかどうか。false は切り捨てを許可することを示します。例 false。
  1. レスポンスのポイント密度 density パラメータ値の説明
選択可能な値 説明
lower やや低い、60 ポイント
low 低い、180 ポイント
medium 中程度、360 ポイント
high 高い、720 ポイント
  • ポイント密度パラメータの優先順位に注意してください。最大密度は density[high] です * interval は density および DQL のポイント密度設定より優先されます。maxPointCount は導出されたポイント数をさらに制限できます。

  • 一般的なクエリの説明

  • 未復旧イベントクエリ

  • OpenAPI クロスサイトデータクエリ

データの可視範囲は、API Key の有効な権限、ワークスペースの権限付与、データアクセスルールによって決まります。

  1. リクエスト JSON の形式エラー

リクエストボディが有効な JSON でない場合、インターフェースはクエリ処理に入る前に HTTP 400 を返し、errorCode は共通エラーコード ft.RequestJsonFormatError になります。content.reason、content.line、content.column はそれぞれ JSON 解析の理由、行番号、列番号を示します。レスポンスは元のリクエストボディをエコーバックしません。

{
  "code": 400,
  "content": {
    "reason": "Expecting property name enclosed in double quotes",
    "line": 22,
    "column": 17
  },
  "errorCode": "ft.RequestJsonFormatError",
  "message": "请求 JSON 格式错误",
  "success": false,
  "traceId": "TRACE-..."
}

QueryHub リクエストフィールド

パラメータ 入力方法
queries[].qtype QueryHub のクエリ項目には queryhub を指定します。
queries[].uuid 任意のクライアントクエリ識別子(例: demo-query)。レスポンスにそのまま返されます。
queries[].query.datasourceId 現在のワークスペースの統合「外部データソース」から有効なデータソース ID を取得します(例: orders)。
queries[].query.mode 必須。native または dql のいずれかを選択し、mode と同じ名前のオブジェクトのみを記入します。
queries[].query.native MySQL または PostgreSQL では language=sql と statement を指定できます(例: SELECT 1 AS value)。さらに parameters 配列を指定することもできます。
queries[].query.dql QueryHub DQL クエリオブジェクト。dql 文を記入し、dqlVersion(デフォルトは queryhub/v1)と parameters オブジェクトを追加できます。
queries[].query.expectedRevision 任意の正整数。呼び出し元が把握しているデータソース設定バージョンで検証するために使用します。

リクエスト例

curl 'https://openapi.guance.com/api/v1/df/query_data_v1' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"queries":[{"qtype":"dql","query":{"q":"M::`cpu`:(`usage_idle`)","timeRange":[1785427200000,1785430800000],"limit":5}}]}'

QueryHub ネイティブ SQL の例

curl 'https://openapi.guance.com/api/v1/df/query_data_v1' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"queries":[{"qtype":"queryhub","uuid":"demo-query","query":{"datasourceId":"orders","mode":"native","native":{"language":"sql","statement":"SELECT 1 AS value"}}}]}'

レスポンス

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 ワークスペース宣言。
content.data[].query_status string QueryHub の項目単位のステータス。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 の成功結果が切り捨てられたかどうか。
レスポンスヘッダー 型 説明
Cache-Control string QueryHub の分岐のレスポンスは no-store です。
{
  "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"
}

QueryHub 成功例

{"code": 200, "content": {"data": [{"uuid": "demo-query", "query_status": "success", "is_running": false, "truncated": false, "series": [{"columns": ["value"], "columnTypes": ["integer"], "values": [[1]]}]}], "declaration": null}, "errorCode": "", "message": "", "success": true, "traceId": "TRACE-EXAMPLE"}

HTTP 200 での QueryHub 項目単位の失敗

{"code": 200, "content": {"data": [{"uuid": "demo-query", "query_status": "failed", "is_running": false, "series": [], "query_error": {"errorCode": "QueryHubForbidden", "message": "没有查询权限。"}}], "declaration": null}, "errorCode": "", "message": "", "success": true, "traceId": "TRACE-EXAMPLE"}

エラーレスポンス

認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。

QueryHub の項目単位の失敗では query_error.errorCode を確認します。データソースが未承認、タイムアウト、またはクエリが拒否された場合は、それぞれ QueryHubForbidden、QueryHubQueryTimeout、QueryHubQueryRejected に対応します。項目単位のエラー識別子には forethought. プレフィックスは付きません。

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 リクエストに必要なクエリ権限がない クエリ権限がありません。 API Key とインスタンスのクエリ権限を確認してください。
400 ft.JsonFormatError JSON のトップレベルまたはクエリ項目の構造が無効、あるいはリクエスト内容が深すぎる 一部の JSON ファイル形式エラー。 トップレベルおよびクエリ項目内の 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/URL body で QueryHub を送信した メッセージは空の場合があります。 POST JSON で 1 ~ 20 個のクエリ項目を送信してください。
422 forethought.QueryHubUseAsync 同期リクエストに複数の QueryHub クエリが含まれている メッセージは空の場合があります。 非同期インターフェースを使用してください。
503 forethought.QueryHubUnavailable QueryHub 機能が有効化されていない、またはサービスが利用不可 クエリサービスまたはデータソースが一時的に利用できません。 権限、クエリ機能、サービス状態を確認してください。

フィードバック

このページは役に立ちましたか?