Skip to content

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
  1. 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
  1. 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.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

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

Feedback

Is this page helpful?