DQL データクエリ¶
POST /api/v1/df/query_data_v1
概要¶
DQL データクエリ
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| queries | array | マルチコマンドクエリ。内容は query オブジェクトのリストです。業務呼び出しでは少なくとも 1 つの query を渡す必要があります。現時点では空配列や省略にも互換性があり、空データを返します 空を許可: False |
|
| fieldTagDescNeeded | boolean | field または tag の説明情報が必要かどうか。デフォルトは false です 空を許可: False |
パラメータ補足説明¶
クエリ説明
本 API は POST と GET の両方をサポートしており、両方式とも同じ JSON オブジェクトのパラメータ構造を使用します：
- POST：完全なパラメータを
application/jsonリクエストボディとして渡します。 - GET：HTTP エンティティボディは使用せず、クエリ文字列の
body=<完全な JSON オブジェクト文字列>で渡します。クライアントはbodyパラメータを URL エンコードする必要があります。 - トップレベルは JSON オブジェクトである必要があり、二重 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です。すべての許可ワークスペースをクエリする場合はtargetRegionを明示的に渡す必要があります。互換性のある書き方workspaceUUID="*"は引き続きサポートされ、同じルールに従います。- ターゲットのワークスペースと
targetRegionは/api/v1/wksp_share/granted_ws_listから取得してください。完全な例は OpenAPI サイト間データクエリ を参照してください。
1、 パラメータ説明
| パラメータ名 | 型 | 必須 | デフォルト値 / 省略時の動作 | 説明 |
|---|---|---|---|---|
| queries | array | []（空データを返す） |
マルチコマンドクエリ。内容は query オブジェクトのリストです。業務クエリでは少なくとも 1 つの query を渡す必要があります | |
| fieldTagDescNeeded | boolean | false |
field または tag の説明情報が必要かどうか |
2、 queries[*] メンバーパラメータの構造説明
| パラメータ名 | 型 | 必須 | デフォルト値 / 省略時の動作 | 説明 |
|---|---|---|---|---|
| qtype | string | dql |
クエリ文のタイプ dql: DQL タイプのクエリ文を示します。promql: PromQL タイプのクエリ文を示します |
|
| query | json | Y | - | 有効なクエリに必須です。欠落している場合や query.q が空の場合は、有効な下流クエリが形成されません |
| query.q | string | 空文字列（通常は有効なクエリが形成されません） | qtype タイプと一致するクエリ文。例: DQL または PromQL クエリ文 | |
| query.ignore_cache | boolean | false |
キャッシュを無効にするかどうか。false はキャッシュを使用することを示します |
|
| query.promqlType | enum | rangeQuery |
qtype=promql の場合に有効です。指定可能な値は instantQuery、rangeQuery です |
|
| query.highlight | boolean | false |
ハイライトデータを表示するかどうか | |
| query.timeRange | array | [] |
外部の時間範囲。DQL で指定しない場合は文内のウィンドウを上書きせず、現在の通常の Select メインルートは GuanceDB が直近 30 分をフォールバックします。PromQL では 2 つの時点を明示的に渡す必要があり、他のエンジンでは動作が異なる場合があります。DQL / PromQL の開始・終了時刻は同じ単位（秒、ミリ秒、マイクロ秒、ナノ秒）を使用する必要があり、混在した場合は HTTP 400 ft.TimeRangeUnitMismatch が返されます。ページネーションカーソルは独立して保持されます |
|
| query.disableMultipleField | bool | true |
単一列モードを有効にするかどうか | |
| query.showLabel | bool | false |
オブジェクトの labels を表示するかどうか | |
| query.funcList | array | [] |
DQL の戻り値を再集計して修飾します。disableMultipleField=false の場合、このパラメータは無効です |
|
| query.slimit | integer | DQL / 下流設定で決定 | 時系列グループのサイズ。メトリクスクエリにのみ有効です | |
| query.soffset | integer | DQL 内の値。DQL でも未設定の場合は追加のオフセットなし | 時系列グループのオフセット。現在のパーサーは正数の外部値のみを使用して DQL で未設定のオフセットを補完し、0 は DQL の既存値をクリアしません |
|
| query.limit | integer | DQL / 下流設定で決定 | ページネーションサイズ | |
| query.offset | integer | DQL 内の値。DQL でも未設定の場合は追加のオフセットなし | ページネーションオフセット。現在のパーサーは正数の外部値のみを使用して DQL で未設定のオフセットを補完し、0 は DQL の既存値をクリアしません |
|
| query.orderby | array | DQL / クエリエンジンで決定 | 並び替えリスト。構造は {fieldName: method} です。メジャーメントクエリでは fieldName=time のみをサポートし、method には desc、asc を指定できます |
|
| query.sorderby | array | DQL / クエリエンジンで決定 | 並び替えリスト。column は単一の値を返す集計関数（min、max、last、avg、p90、p95、count など）をサポートします | |
| query.order_by | array | DQL / クエリエンジンで決定 | Doris エンジン互換の並び替えリスト。構造は [{"column": "field", "order": "DESC"}] です |
|
| query.sorder_by | array | DQL / クエリエンジンで決定 | Doris エンジン互換の時系列並び替えリスト。構造は [{"column": "field", "order": "DESC"}] です |
|
| query.density | string | DQL / クエリエンジンで決定 | レスポンスポイントの密度。DQL 文内の制御パラメータより優先されます | |
| query.interval | number | DQL / クエリエンジンで決定 | 時間スライスの間隔。Kodo の int64 範囲に変換可能で 1ms 以上の整数のみ受け付けます。単位は interval_unit で指定します |
|
| query.interval_unit | string | s |
interval の単位。s、ms を指定できます |
|
| query.align_time | boolean | false |
クエリエンジンの時間グリッドに合わせて時間スライスを整列するかどうか | |
| query.tz | string | Asia/Shanghai |
クエリのタイムゾーン | |
| query.search_after | array | ページネーションマーカーを設定しない | ディープページネーションパラメータ。次のリクエストでは、前回のレスポンスの search_after を渡す必要があります |
|
| query.maxPointCount | integer | DQL / クエリエンジンで決定 | 最大ポイント数 | |
| query.workspaceUUID | string | 現在のワークスペース | クエリ対象の単一の許可ワークスペース UUID。* は targetRegion 内のすべての許可済みワークスペースをクエリすることを示します |
|
| query.workspaceUUIDs | array | 設定しない | クエリ対象の許可ワークスペース UUID のリスト。空でない場合は query.workspaceUUID より優先されます。同じリスト内の UUID は同じサイトに属している必要があります。["*"] は targetRegion 内のすべての許可済みワークスペースをクエリすることを示します。両方のフィールドを同時に渡すことは推奨しません |
|
| query.targetRegion | string | 現在のワークスペースクエリでは現在のサイトを暗黙的に使用。すべての許可ワークスペースをクエリする場合はデフォルト値なし | 許可ワークスペースが属するサイトの regionCode。/wksp_share/granted_ws_list 内で対象の workspaceUUID と同じグループの regionCode から取得します。明示的なサイト間クエリでは渡すことを推奨し、すべての許可済みワークスペースをクエリする場合は明示的に渡す必要があります。互換性のある書き方 workspaceUUID="*" も同じルールに従います |
|
| query.output_format | string | 既存の JSON レスポンス形式 | lineprotocol に設定するとラインプロトコルを返します |
|
| query.cursor_time | integer | カーソルを設定しない | 最初のセグメントクエリでは end_time に設定します。以降はレスポンス内の next_cursor_time を渡します |
|
| query.cursor_token | string | トークンを設定しない | ページネーション時は前回のレスポンスの next_cursor_token を渡します。渡さない場合、同じタイムスタンプのデータがページ送り時にスキップされる可能性があります |
|
| query.disable_sampling | bool | false |
サンプリングを無効にするかどうか | |
| query.disable_truncate | bool | false |
返却内容の切り詰めを無効にするかどうか。false は切り詰めを許可することを示します |
3、 レスポンスポイント密度 density パラメータ値の説明
| 指定可能な値 | 説明 |
|---|---|
| lower | やや低、60 ポイント |
| low | 低、180 ポイント |
| medium | 中、360 ポイント |
| high | 高、720 ポイント |
- ポイント密度パラメータの優先順位に注意してください。最大密度は
density[high]です。 * maxPointCount > interval > density > dql 文内の制御パラメータ
4、 一般的なクエリの説明
- 未復旧イベントクエリ
-
注: OpenAPI でデータクエリを実行する場合、デフォルトは管理者ロールです。データアクセスルールの制限を受ける可能性があることに注意してください。
5、 リクエスト JSON 形式エラー
リクエストボディが有効な JSON でない場合、API はクエリ処理に入る前に 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-..."
}
リクエスト例¶
curl 'https://openapi.guance.com/api/v1/df/query_data_v1' \
-H 'Content-Type: application/json' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-raw $'{"queries":[{"qtype":"dql","query":{"q":"M::`cpu`:(avg(`usage_idle`))","_funcList":[],"funcList":[],"maxPointCount":720,"interval":10,"align_time":true,"sorder_by":[{"column":"`#1`","order":"DESC"}],"slimit":20,"disable_sampling":false,"timeRange":[1708911106000,1708912906999],"tz":"Asia/Shanghai"}}]}' \
--compressed
curl --get '<Endpoint>/api/v1/df/query_data_v1' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode 'body={"queries":[{"qtype":"dql","query":{"q":"M::`cpu`:(avg(`usage_idle`))"}}]}' \
--compressed
レスポンス¶
{
"code": 200,
"content": {
"data": [
{
"async_id": "",
"column_names": [
"avg(usage_idle)"
],
"complete": false,
"cost": "14.815745ms",
"index_name": "",
"index_names": "",
"index_store_type": "",
"interval": 10000,
"is_running": false,
"max_point": 181,
"next_cursor_time": -1,
"points": null,
"query_parse": {
"fields": {
"avg(usage_idle)": "usage_idle"
},
"funcs": {
"avg(usage_idle)": [
"avg"
]
},
"namespace": "metric",
"sources": {
"cpu": "exact"
}
},
"query_type": "example_db",
"sample": 1,
"scan_completed": false,
"scan_index": "",
"series": [
{
"columns": [
"time",
"avg(usage_idle)"
],
"name": "cpu",
"units": [
null,
null
],
"values": [
[
1708912900000,
75.68748278863335
],
[
1708912890000,
80.20737341208
],
[
1708912880000,
73.23943236630001
],
[
1708912870000,
71.08465385756001
],
[
1708912860000,
75.12657005472002
],
[
1708912850000,
84.19848645072001
],
[
1708912840000,
81.59161169702
],
[
1708912830000,
77.14274451154
]
]
}
],
"window": 10000
}
],
"declaration": {
"b": [
"asfawfgajfasfafgafwba",
"asfgahjfaf"
],
"business": "aaa",
"organization": "6540c09e4243b300077a9675"
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "10888927517520616916"
}