DQL Data Query¶
POST /api/v1/df/query_data_v1
Overview¶
DQL Data Query
Body Request Parameters¶
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| queries | array | Multi-command query: a list of query objects. Business calls should pass at least one query. The API currently accepts an empty array or an omitted value and returns empty data. Allow empty: False |
|
| fieldTagDescNeeded | boolean | Whether field or tag description information is needed; default false Allow empty: False |
Parameter Supplementary Description¶
Query Description
The default values of optional parameters represent the behavior when the caller omits the parameter:
- When
query.timeRangeis not passed, Studio passestime_range: []downstream, does not add a fixed time window on the Studio side, and does not override the time range within the DQL statement. Currently, the main path for ordinary DQL Select queries falls back to querying the last 30 minutes in GuanceDB v1.52.0. This value is part of the downstream implementation and is not a unified OpenAPI default for all qtypes or all storage engines. PromQL queries require two time points to be explicitly provided. To ensure consistent behavior across versions and engines, it is recommended to explicitly pass the two millisecond timestamps[startTimeMs, endTimeMs]. -
query.limit,query.slimit, sorting, maximum point count, and query time limits are affected by the DQL statement, downstream service configuration, and the storage engine. There are no unified fixed OpenAPI defaults; callers that need stable boundaries should pass these values explicitly. -
Parameter Description
| Parameter | Type | Required | Default Value / Omission Behavior | Description |
|---|---|---|---|---|
| queries | array | [] (returns empty data) |
Multi-command query: a list of query objects. Business queries should pass at least one query | |
| fieldTagDescNeeded | boolean | false |
Whether field or tag description information is needed |
- queries[*] Member Parameter Structure Description
| Parameter | Type | Required | Default Value / Omission Behavior | Description |
|---|---|---|---|---|
| qtype | string | dql |
Type of query statement dql: DQL type query statement;promql: PromQL type query statement |
|
| query | json | Y | - | Required for a valid query; a missing value or an empty query.q does not form a valid downstream query |
| query.q | string | Empty string (usually does not form a valid query) | Query statement consistent with the qtype, such as a DQL or PromQL query statement | |
| query.ignore_cache | boolean | false |
Whether to disable the cache; false means the cache is used |
|
| query.disable_streaming_aggregation | boolean | true (forced for OpenAPI) |
This API always disables streaming aggregation. Omitting this parameter or explicitly passing false does not enable streaming aggregation |
|
| query.promqlType | enum | rangeQuery |
Effective when qtype=promql; available values are instantQuery and rangeQuery |
|
| query.highlight | boolean | false |
Whether to display highlighted data | |
| query.timeRange | array | [] |
External time range. When not passed for DQL, the in-statement window is not overridden, and the current ordinary Select main route falls back to the last 30 minutes in GuanceDB. PromQL requires two time points to be explicitly provided, and other engines may behave differently. The start and end times for DQL / PromQL must use the same unit (seconds, milliseconds, microseconds, or nanoseconds); mixing units returns HTTP 400 ft.TimeRangeUnitMismatch. Pagination cursors remain independent |
|
| query.disableMultipleField | bool | true |
Whether to enable single-column mode | |
| query.showLabel | bool | false |
Whether to display the labels of the object | |
| query.funcList | array | [] |
Applies further aggregation and modification to DQL return values; this parameter is invalid when disableMultipleField=false |
|
| query.slimit | integer | Determined by DQL / downstream configuration | Time series grouping size; valid only for metric queries | |
| query.soffset | integer | Value in the DQL; no additional offset when the DQL does not set one | Time series grouping offset. The current parser only fills in offsets not set in the DQL using positive external values; 0 does not clear existing DQL values |
|
| query.limit | integer | Determined by DQL / downstream configuration | Page size | |
| query.offset | integer | Value in the DQL; no additional offset when the DQL does not set one | Page offset. The current parser only fills in offsets not set in the DQL using positive external values; 0 does not clear existing DQL values |
|
| query.orderby | array | Determined by DQL / query engine | Sort list with the structure {fieldName: method}; Measurement queries support only fieldName=time, and method can be desc or asc |
|
| query.sorderby | array | Determined by DQL / query engine | Sort list; column supports aggregation functions that return a single value, such as min, max, last, avg, p90, p95, and count | |
| query.order_by | array | Determined by DQL / query engine | Doris engine-compatible sort list with the structure [{"column": "field", "order": "DESC"}] |
|
| query.sorder_by | array | Determined by DQL / query engine | Doris engine-compatible time series sort list with the structure [{"column": "field", "order": "DESC"}] |
|
| query.density | string | Determined by DQL / query engine | Response point density; takes precedence over control parameters in the DQL statement | |
| query.interval | number | Determined by DQL / query engine | Time slice interval. Only integers that can be converted to values within the Kodo int64 range and are not less than 1ms are accepted; the unit is specified by interval_unit |
|
| query.interval_unit | string | s |
Unit of interval; available values are s and ms |
|
| query.align_time | boolean | false |
Whether to align time slices to the query engine's time grid | |
| query.tz | string | Asia/Shanghai |
Query time zone | |
| query.search_after | array | No pagination marker set | Deep pagination parameter; the next request should pass the search_after from the previous response |
|
| query.maxPointCount | integer | Determined by DQL / query engine | Maximum point count | |
| query.workspaceUUID | string | Current workspace | UUID of the granted workspace to query; * means query all granted workspaces within targetRegion |
|
| query.workspaceUUIDs | array | Not set | List of granted workspace UUIDs to query; when non-empty, takes precedence over query.workspaceUUID. All items in the same list must belong to the same site; ["*"] means query all granted workspaces within targetRegion. It is recommended not to pass both fields at the same time |
|
| query.targetRegion | string | Current workspace queries implicitly use the current site; no default when querying all granted workspaces | The regionCode of the site to which the granted workspace belongs; obtain it from the regionCode grouped with the target workspaceUUID in /wksp_share/granted_ws_list. It is recommended to pass it for explicit cross-site queries, and it must be explicitly passed when querying all granted workspaces; the compatible form workspaceUUID="*" follows the same rule |
|
| query.output_format | string | Existing JSON response format | Returns line protocol when set to lineprotocol |
|
| query.cursor_time | integer | No cursor set | Set to end_time for the first segmented query; afterwards, pass the next_cursor_time from the response |
|
| query.cursor_token | string | No token set | Pass the next_cursor_token from the previous response when paging; if not passed, data with the same timestamp may be skipped when paging |
|
| query.disable_sampling | bool | false |
Whether to disable sampling | |
| query.disable_truncate | bool | false |
Whether to disable truncation of returned content; false means truncation is allowed |
- Response Point Density
densityParameter Value Description
| Optional Value | Description |
|---|---|
| lower | Low, 60 points |
| low | Low, 180 points |
| medium | Medium, 360 points |
| high | High, 720 points |
-
Note the priority of point density parameters, maximum density
density[high]* maxPointCount > interval > density > control parameters in dql statement -
Common Query Description
-
Note: When using openapi interface for data query, default is admin role. Note that it may be subject to data access rule restrictions
Request Example¶
curl 'https://openapi.truewatch.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
Response¶
Response Fields¶
content.data[i] corresponds to queries[i] in the request. Common fields are listed below; some are returned only for the applicable query scenarios.
| Field | Type | Description |
|---|---|---|
series |
array | Query results returned in groups. |
series[].name |
string | Data source name, such as a measurement name. |
series[].tags |
object | Tags for the current group. |
series[].columns |
array | Result column names, in the same order as the values in each row of values. |
series[].values |
array | Result data. Each item is one row. |
series[].units |
array | Column units, corresponding to columns by position. |
time_range |
array | Time range of this query, in milliseconds. |
interval |
integer | Window interval, in milliseconds. |
window |
integer | Window time range, in milliseconds. |
next_cursor_time |
integer | Time cursor for the next segment, in microseconds. If nonnegative, pass it unchanged as query.cursor_time in the next request. A negative value indicates the end of segmented querying. |
next_cursor_token |
string | If nonempty, pass it as query.cursor_token in the next request. |
sample |
number | Sampling ratio or approximate-result indicator. 0 < sample < 1 means the result was sampled or affected by server-side limits. The value represents a sampling ratio only when actual sampling occurred. |
sampling_required |
boolean | When true, do not disable sampling and rerun the query. |
is_order_by_ignored |
boolean | Whether the specified sort order was ignored and replaced with descending time order. |
warnings |
array | Informational messages returned with a successful query. |
warnings[].code |
string | Warning code. |
warnings[].message |
string | Warning description. |
warnings[].details[].metadata |
object | Warning context. Its contents depend on the warning type. |
Query Statistics¶
content.data[i].query_progress contains query progress and scan statistics.
| Field | Type | Description |
|---|---|---|
total_percentage |
number | Query progress percentage, from 0 to 100. |
total_rows |
integer | Total number of rows planned for scanning. May be 0 before query planning completes. |
total_compressed_bytes |
integer | Compressed size of the data planned for scanning, in bytes. May be 0 before planning completes. |
total_uncompressed_bytes |
integer | Uncompressed size of the data planned for scanning, in bytes. May be 0 before planning completes. |
scanned_rows |
integer | Number of rows already scanned. |
scanned_compressed_bytes |
integer | Compressed size of the data already scanned, in bytes. |
scanned_uncompressed_bytes |
integer | Uncompressed size of the data already scanned, in bytes. |
Response Example¶
{
"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"
}