コンテンツにスキップ

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 が優先されます。

  1. 通常のバッチクエリの JSON オブジェクト
パラメータ名 型 必須 説明
queries array Y 複数コマンドのクエリ。内容は query オブジェクトからなるリストです。
fieldTagDescNeeded boolean field または tag の説明情報が必要かどうか
  1. 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。
  1. レスポンスのポイント密度 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 パラメータが渡された リクエストフィールドの検証に失敗しました。 パラメータ表にあるクエリフィールドのみを使用してください。

フィードバック

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