DQL Data Query¶

POST /api/v1/df/query_data_v1

Overview¶

DQL Data Query

Body Request Parameters¶

Parameter	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

Additional Parameter Notes¶

Query Notes

This API supports both POST and GET, and both methods use the same JSON object parameter structure:

POST: The full parameters are passed as the application/json request body;
GET: The HTTP entity body is not used; parameters are passed in the query string via body=<full JSON object string>, and the client should URL-encode the body parameter;
The top level must be a JSON object. Double-JSON-encoded strings, arrays, null, numbers, or booleans are not accepted.

The response content.data[i].warnings[] may contain DQLDataAccessScopeRestricted:

details[0].metadata.namespace is fixed to logging in this release;
details[0].metadata.restriction=partial indicates that only data from log indexes for which the caller has permission is returned;
details[0].metadata.restriction=all indicates that the caller has no data access permission for any of the related log indexes, and an empty result is returned;
The HTTP status code remains 200, and the warning coexists with existing GuanceDB/Kodo warnings.

The default values of optional parameters represent the behavior when the caller omits the parameter:

When query.timeRange is not passed, Studio passes time_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.

Cross-workspace / cross-site query constraints:

All queries[*] in a single request can only point to the same targetRegion; when multiple sites need to be queried, split the request by site and merge the results on the client side.
A non-empty workspaceUUIDs takes precedence over workspaceUUID; when workspaceUUIDs is an empty array or null, it falls back to workspaceUUID. It is recommended not to pass both fields at the same time. Both fields can be omitted for current workspace queries; when explicitly querying a granted workspace, it is recommended to also pass the targetRegion to which the granted workspace belongs.
When workspaceUUIDs=["*"], the parameter without a default value is targetRegion; targetRegion must be explicitly passed when querying all granted workspaces. The compatible form workspaceUUID="*" remains supported and follows the same rule.
The target workspace and targetRegion should be obtained via /api/v1/wksp_share/granted_ws_list. For a complete example, refer to OpenAPI Cross-Site Data Query.
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

Structure of queries[*] Member Parameters

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.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 density Parameter Values

Value	Description
lower	Lower: 60 points
low	Low: 180 points
medium	Medium: 360 points
high	High: 720 points

Note the priority of the point density parameter: the maximum density is density[high]. maxPointCount > interval > density > control parameters in the DQL statement
Common Query Notes
Unrecovered Events Query
OpenAPI Cross-Site Data Query

Note: When performing data queries through the OpenAPI, the default role is Administrator. Note that queries may be restricted by Data Access rules.
Request JSON Format Errors

When the request body is not valid JSON, the API returns HTTP 400 before entering query processing, and errorCode is the shared error code ft.RequestJsonFormatError. content.reason, content.line, and content.column indicate the JSON parsing reason, line number, and column number, respectively; the response does not echo the original request body.

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

Request Examples¶

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

Response¶

{
    "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"
}