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 Allows empty: False
fieldTagDescNeeded	boolean		Whether field or tag description information is needed Allows empty: False

Additional Parameter Notes¶

Query Description

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

details[0].metadata.namespace is fixed to logging for the current release;
details[0].metadata.restriction=partial indicates that only data from log indices with access permissions is returned;
details[0].metadata.restriction=all indicates that none of the relevant log indices have data access permissions, and an empty result is returned;
HTTP status code remains 200; warnings coexist with existing GuanceDB/Kodo warnings.
Parameter Description

Parameter Name	type	Required	Description
queries	array	Y	Multi-command query, a list of query objects
fieldTagDescNeeded	boolean		Whether field or tag description information is needed

Queries[*] Member Parameter Structure Description

Parameter Name	type	Required	Description
qtype	string	Y	Type of query statement dql: indicates a DQL type query statement; promql: indicates a PromQL type query statement
query	json	Y	Query structure
query.q	string		Query statement consistent with the qtype, e.g., DQL or PromQL query statement
query.ignore_cache	boolean		Whether to disable cache for the query; default is false, meaning cache is used
query.promqlType	enum		Effective when qtype=promql; the query type for PromQL, optional values: `instantQuery` and `rangeQuery`, default value is `rangeQuery`
query.highlight	boolean		Whether to display highlighted data
query.timeRange	array		List of timestamps for the time range
query.disableMultipleField	bool		Whether to enable single-column mode; default is `true`
query.showLabel	bool		Whether to display object labels; default is none
query.funcList	array		Re-aggregation modifiers for DQL return values; note that when disableMultipleField=false, this parameter is invalid
query.slimit	integer		Time series group size; only valid for metrics queries
query.soffset	integer		Time series group offset
query.limit	integer		Number of results per page
query.offset	integer		Page offset
query.orderby	array		Sort list, `{fieldName:method}`; note that for measurement queries, sorting only supports fieldName=time; method in ["desc", "asc"]; note that for measurement queries, sorting only supports fieldName=time
query.sorderby	array		Sort list; the column in sorderby is an expression, supporting all aggregation functions that return a single value: min, max, last, avg, p90, p95, count. `{fieldName:method}`, structure consistent with orderby
query.order_by	array		Sort list, structure is [{"column": "field", "order": "DESC"}]; compatible field for Doris engine
query.sorder_by	array		Sort list, structure is [{"column": "field", "order": "DESC"}]; compatible field for Doris engine
query.density	string		Response point density; priority is lower than autoDensity and higher than the density set in the DQL statement
query.interval	number		Time slice interval; accepts only positive numbers that can be converted to an int64 within the Kodo range and are not less than 1ms in integer milliseconds; default unit is seconds, can be specified as milliseconds via interval_unit
query.interval_unit	string		Unit of interval, optional `s` or `ms`, default is `s`
query.search_after	array		Pagination query marker. Use the search_after value from the previous request's response as the parameter for the current request.
query.maxPointCount	integer		Maximum number of points
query.workspaceUUID	string		UUID of the workspace to query; "*" means query all authorized workspaces. Refer to the workspace reference endpoint /wksp_share/granted_ws_list
query.workspaceUUIDs	array		UUIDs of the workspaces to query; priority is higher than query.workspaceUUID. ["*"] means query all authorized workspaces. Refer to the workspace reference endpoint /wksp_share/granted_ws_list
query.targetRegion	string		Required when specifying the query workspace as ["*"]
query.output_format	string		lineprotocol: output in line protocol format; if not filled, the default output format remains unchanged
query.cursor_time	integer		Segmented query threshold: for the first segmented query, set cursor_time to end_time; for subsequent queries, set cursor_time to the next_cursor_time in the response
query.cursor_token	string		Pagination query token (value of cursor_token returned by the engine): for pagination, set the next_cursor_token from the previous query response as the cursor_token for the current query; requests without a cursor_token may cause data with the same timestamp to be skipped during pagination
query.disable_sampling	bool		Sampling disable switch; default value is false
query.disable_truncate	bool		Indicates whether to truncate the returned content; default is none

Response Point Density density Parameter Value Description

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

Note the priority of the density parameter: maximum density density[high] * maxPointCount > interval > density > control parameters in the DQL statement
Common Query Descriptions
Unrecovered Event Query

Note: When using the OpenAPI for data queries, the role defaults to Admin. Be aware that data access rules may apply.

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¶

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