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

  • 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
  1. 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
  1. Response Point Density density Parameter 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

  • Unrecovered Event Query

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