Skip to content

DQL Data Query (Legacy)


POST /api/v1/df/query_data

Overview

DQL Data Query

Query Request Parameters

Parameter Name Type Required Description
body string DQL query structure
Nullable: False
queries_body string DQL query structure (parameter retired on 2023-08-11)
Nullable: False
search_after string Pagination query request parameter (parameter retired on 2023-08-11)
Nullable: False

Additional Parameter Notes

Query Notes

This endpoint is a legacy compatibility entry point. For new integrations, we recommend using POST /api/v1/df/query_data_v1. The legacy GET continues to pass parameters using body=<URL-encoded JSON>; do not double-encode the JSON.

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

For cross-workspace/cross-site queries, all queries[*] in a single request must point to the same targetRegion. To query multiple sites, split the requests by site and merge the results on the client side. The target workspace and targetRegion should be obtained via /api/v1/wksp_share/granted_ws_list. For details, refer to: OpenAPI Cross-Site Data Query.

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 with permission for the relevant log indexes is returned;
  • details[0].metadata.restriction=all indicates that no data access permission is available for any of the relevant log indexes, and an empty result is returned;

  • The HTTP status code remains 200, and this warning coexists with existing GuanceDB/Kodo warnings.

  • Query String Element Field Description

Parameter Name type Required Description
body string One of body or queries_body Query request body
queries_body[*] string One of body or queries_body (Legacy parameter, retired on 2023-08-10) Query list
search_after string (Legacy parameter, retired on 2023-08-10; in the new version, this parameter has been moved into the query structure) Query pagination data. Defaults to [] on the first query. To query more paginated data, include the search_after field from the previous query result to fetch subsequent data.

body and the compatibility parameter queries_body are conditionally required; please provide at least one non-empty, valid JSON value. When both are provided, the non-empty queries_body takes precedence.

  1. JSON Structure Parameter Description in body
Parameter Name type Required Description
queries array Y Multi-command query; its content is 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 the query statement
dql: DQL query statement;
promql: PromQL query statement
query json Y Query structure
query.q string Query statement consistent with the qtype, for example a DQL or PromQL query statement
query.ignore_cache boolean Whether to disable the cache. Defaults to false, meaning the cache is used
query.promqlType enum Takes effect when qtype=promql. Available values: instantQuery, rangeQuery; defaults to rangeQuery
query.highlight boolean Whether to display highlighted data
query.timeRange array List of timestamps for the time range. The start and end times of DQL/PromQL must use the same unit (seconds, milliseconds, microseconds, or nanoseconds); mixed units return HTTP 400 ft.TimeRangeUnitMismatch. Pagination cursors remain independent
query.disableMultipleField bool Whether to enable single-column mode. Defaults to true
query.showLabel bool Whether to display the labels of the object. Defaults to false
query.funcList array Re-aggregates and modifies DQL return values; this parameter is invalid when disableMultipleField=false
query.slimit integer Time Series group size; only valid for metric queries
query.soffset integer Time Series group offset
query.limit integer Page size
query.offset integer Pagination offset
query.orderby array Sort list in the structure {fieldName: method}. Measurement queries only support fieldName=time, and method can be desc or asc
query.density string Point density of the response. Its priority is lower than autoDensity but higher than the density set in the DQL statement
query.interval number Time slice interval. Only positive integers that can be represented within the Kodo int64 range and are not less than 1ms (integer milliseconds) are accepted. The default unit is seconds; interval_unit can be used to specify milliseconds
query.interval_unit string Unit of interval. Available values: s, ms; defaults to s
query.search_after array Pagination marker returned by this endpoint, to be passed in the next request
query.maxPointCount integer Maximum number of points
query.workspaceUUID string UUID of a single authorized workspace to query; * means querying all authorized workspaces within targetRegion
query.workspaceUUIDs array List of authorized workspace UUIDs to query. When non-empty, it takes precedence over query.workspaceUUID. All UUIDs in the same list must belong to the same site; ["*"] means querying all authorized workspaces within targetRegion. It is recommended not to pass both fields at the same time
query.targetRegion string regionCode of the site where the authorized workspace resides. 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 is required when querying *
query.output_format string lineprotocol: line protocol output. If not specified, the current output format is preserved
query.cursor_time integer Segmented query threshold: set it to end_time for the first segmented query; afterwards, pass the next_cursor_time from the response
query.cursor_token string Pagination query token (the cursor_token value returned by the engine): for paginated queries, set the next_cursor_token returned by the previous query as the cursor_token of the current query. Requests without cursor_token may cause data with the same timestamp to be skipped when paging
query.disable_sampling bool Sampling disable switch. Defaults to false
query.disable_truncate bool Whether to disable truncation of returned content. Defaults to false, meaning truncation is allowed
  1. Response Point Density density Parameter Values
Available Value Description
lower Lower, 60 points
low Low, 180 points
medium Medium, 360 points
high High, 720 points

Note: When performing data queries through the OpenAPI endpoint, the default role is Administrator. Be aware that you may be subject to Data Access rule restrictions.

Request Example

curl 'https://openapi.guance.com/api/v1/df/query_data?body=\{%22queries%22:\[\{%22uuid%22:%2205ea25f0-2fa3-11ee-aa03-57233270ef0c%22,%22qtype%22:%22dql%22,%22query%22:\{%22q%22:%22L::re(`.*`):(`*`)\{+`index`+IN+\[%27default%27\]+\}%22,%22highlight%22:true,%22limit%22:50,%22orderby%22:\[\{%22time%22:%22desc%22\}\],%22_funcList%22:\[\],%22funcList%22:\[\],%22disableMultipleField%22:false,%22align_time%22:false,%22is_optimized%22:true,%22offset%22:0,%22search_after%22:\[1690808645037,538070,%22L_1690808645037_cj3r2itnel8fnfu5tlag%22\],%22timeRange%22:\[1690807857000,1690808757999\],%22tz%22:%22Asia/Shanghai%22\}\}\],%22expensiveQueryCheck%22:true\}' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--compressed

Response

{
    "code": 200,
    "content": {
        "data": [
            {
                "AsyncTaskPayload": null,
                "async_id": "",
                "column_names": [
                    "container_id",
                    "source",
                    "filepath",
                    "image",
                    "index",
                    "df_metering_size",
                    "__namespace",
                    "host",
                    "log_read_offset",
                    "__docid",
                    "filename",
                    "service",
                    "image_name",
                    "image_short_name",
                    "image_tag",
                    "log_read_lines",
                    "message",
                    "log_read_time",
                    "container_name",
                    "container_type",
                    "message_length",
                    "create_time",
                    "container_runtime_name",
                    "date_ns",
                    "status"
                ],
                "complete": false,
                "cost": "19ms",
                "index_name": "",
                "index_names": "",
                "index_store_type": "es",
                "is_running": false,
                "points": null,
                "query_type": "",
                "raw_query": "{\\\"aggs\\\":{},\\\"_source\\\":{\\\"excludes\\\":[\\\"message@json\\\"],\\\"includes\\\":[]},\\\"query\\\":{\\\"bool\\\":{\\\"filter\\\":[{\\\"term\\\":{\\\"__namespace\\\":\\\"logging\\\"}},{\\\"range\\\":{\\\"date\\\":{\\\"gte\\\":\\\"1680187562081\\\",\\\"lte\\\":\\\"1680230762081\\\"}}},{\\\"bool\\\":{\\\"should\\\":[{\\\"terms\\\":{\\\"index\\\":[\\\"default\\\"]}}]}}]}},\\\"size\\\":50,\\\"sort\\\":[{\\\"date\\\":{\\\"missing\\\":\\\"_last\\\",\\\"order\\\":\\\"desc\\\",\\\"unmapped_type\\\":\\\"long\\\"}},{\\\"date_ns\\\":{\\\"missing\\\":\\\"_last\\\",\\\"order\\\":\\\"desc\\\",\\\"unmapped_type\\\":\\\"long\\\"}},{\\\"__docid\\\":{\\\"missing\\\":\\\"_first\\\",\\\"order\\\":\\\"desc\\\",\\\"unmapped_type\\\":\\\"string\\\"}}],\\\"search_after\\\":[1680226330509,8572,\\\"L_1680226330509_cgj4hqbrhi85kl1m6os0\\\"],\\\"timeout\\\":\\\"54s\\\"}",
                "search_after": [
                    1680226330508,
                    82936,
                    "L_1680226330508_cgj4hbdepb7fcn07sf60"
                ],
                "series": [
                    {
                        "columns": [
                            "container_id",
                            "time",
                            "source",
                            "filepath",
                            "image",
                            "index",
                            "df_metering_size",
                            "__namespace",
                            "host",
                            "log_read_offset",
                            "__docid",
                            "filename",
                            "service",
                            "image_name",
                            "image_short_name",
                            "image_tag",
                            "log_read_lines",
                            "message",
                            "log_read_time",
                            "container_name",
                            "container_type",
                            "message_length",
                            "create_time",
                            "container_runtime_name",
                            "date_ns",
                            "status"
                        ],
                        "values": [
                            [
                                "2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380",
                                1680226330509,
                                "test",
                                "/var/lib/docker/containers/2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380/2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380-json.log",
                                "test:test",
                                "default",
                                1,
                                "logging",
                                "izbp152ke14timzud0du15z",
                                149232879,
                                "L_1680226330509_cgj4hqbrhi85kl1m6org",
                                "2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380-json.log",
                                "test",
                                "test",
                                "test",
                                "test",
                                147890,
                                "ddtrace.profiling.exporter.http.UploadFailed: [Errno 101] Network is unreachable",
                                1680226330508872700,
                                "compose_python_ddtrace_web_b_1",
                                "docker",
                                80,
                                1680230633485,
                                "compose_python_ddtrace_web_b_1",
                                8571,
                                "unknown"
                            ],
                            [
                                "2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380",
                                1680226330509,
                                "test",
                                "/var/lib/docker/containers/2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380/2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380-json.log",
                                "test:test",
                                "default",
                                1,
                                "logging",
                                "izbp152ke14timzud0du15z",
                                149232879,
                                "L_1680226330509_cgj4hqbrhi85kl1m6or0",
                                "2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380-json.log",
                                "test",
                                "test",
                                "test",
                                "test",
                                147889,
                                "    raise retry_exc from fut.exception()",
                                1680226330508872700,
                                "compose_python_ddtrace_web_b_1",
                                "docker",
                                40,
                                1680230633485,
                                "compose_python_ddtrace_web_b_1",
                                8570,
                                "unknown"
                            ],
                            [
                                "2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380",
                                1680226330509,
                                "test",
                                "/var/lib/docker/containers/2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380/2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380-json.log",
                                "test:test",
                                "default",
                                1,
                                "logging",
                                "izbp152ke14timzud0du15z",
                                149232879,
                                "L_1680226330509_cgj4hqbrhi85kl1m6oqg",
                                "2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380-json.log",
                                "test",
                                "test",
                                "test",
                                "test",
                                147888,
                                "  File \\\"/usr/local/lib/python3.7/site-packages/tenacity/__init__.py\\\", line 361, in iter",
                                1680226330508872700,
                                "compose_python_ddtrace_web_b_1",
                                "docker",
                                87,
                                1680230633485,
                                "compose_python_ddtrace_web_b_1",
                                8569,
                                "unknown"
                            ],
                            [
                                "2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380",
                                1680226330508,
                                "test",
                                "/var/lib/docker/containers/2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380/2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380-json.log",
                                "test:test",
                                "default",
                                1,
                                "logging",
                                "izbp152ke14timzud0du15z",
                                149228783,
                                "L_1680226330508_cgj4hbdepb7fcn07sf60",
                                "2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380-json.log",
                                "test",
                                "test",
                                "test",
                                "test",
                                147841,
                                "KeyError: 'dd.service'",
                                1680226330507918000,
                                "compose_python_ddtrace_web_b_1",
                                "docker",
                                22,
                                1680230573234,
                                "compose_python_ddtrace_web_b_1",
                                82936,
                                "unknown"
                            ]
                        ]
                    }
                ],
                "total_hits": 10000
            }
        ]
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "TRACE-CD50CBBD-E29B-4F58-BD6B-618EED50920A"
}

Feedback

Is this page helpful?