DQL Asynchronous Data Query¶

POST /api/v1/df/asynchronous/query_data

Overview¶

Request Body Parameters¶

Supplementary Parameter Notes¶

Query Notes

This interface supports both POST and GET, and both methods use the same JSON object parameter structure: POST sends the complete parameters in the application/json request body; GET passes body=<complete JSON object string> in the query string and URL-encodes it. The top level does not accept string, array, null, number, or boolean.

The final response of an asynchronous query may contain DQLDataAccessScopeRestricted in content.data[i].warnings[]. details[0].metadata.namespace is fixed to logging in the current release. restriction=partial means only data from indexes with permission is returned; restriction=all means no permission for the related log indexes and an empty result is returned. The HTTP status code and request parameters remain unchanged.

async_id Lifecycle (Important)

1. When initiating a new logical query, you must omit queries[i].async_id. If the server switches to asynchronous execution, it returns content.data[i].is_running=true and a non-empty content.data[i].async_id in the same position.
2. Only when is_running is strictly true and async_id is non-empty should this ID be used to poll the same task. Polling requests should keep the item's qtype, query, target workspace, and targetRegion unchanged, and put the ID back into the corresponding queries[i].async_id.
3. When is_running=false, the task has ended. Even if the async_id field still appears in the response structure, the caller must not continue carrying the old ID in the next new query. Both new queries and queries with modified query statements/time ranges must omit async_id again.
4. async_id belongs to only one query item and one task. It is not a session ID, nor a pagination cursor. In batch queries, content.data[i] corresponds to queries[i] by array index. Do not use the ID of one query item for another query item. To reduce mapping errors, it is recommended to submit only one query per asynchronous call.
5. If is_running=true but async_id is empty, treat it as an abnormal response that cannot be polled. Do not fill in a historical ID. Record the traceId and re-initiate the logical query with a limited retry policy, or contact technical support.

It is recommended to use incremental backoff and set a total timeout to avoid polling without intervals. After the task completes, if pagination is needed, use search_after, next_cursor_time, or next_cursor_token returned in the final result. Do not use async_id as a substitute for pagination parameters.

First request (without async_id)

{
  "queries": [
    {
      "qtype": "dql",
      "query": {
        "q": "L::re(`.*`):(`message`)",
        "timeRange": [1772516130000, 1772519730000],
        "limit": 100,
        "workspaceUUIDs": ["wksp_target"],
        "targetRegion": "region_code"
      }
    }
  ]
}

Poll the same task only while it is running

{
  "queries": [
    {
      "async_id": "async_task_id_from_content_data_0",
      "qtype": "dql",
      "query": {
        "q": "L::re(`.*`):(`message`)",
        "timeRange": [1772516130000, 1772519730000],
        "limit": 100,
        "workspaceUUIDs": ["wksp_target"],
        "targetRegion": "region_code"
      }
    }
  ]
}

Cross-site queries must also obey the restriction that one request queries only one targetRegion. For information on obtaining the target workspace and site code and the complete call flow, see: OpenAPI Cross-Site Data Query.

1. Parameter Description

1. Description of queries[*] Member Parameter Structure

Compared with synchronous queries, each query item additionally supports async_id; it is used only for polling a task that is still running.

1. Response Point Density density Parameter Values

Note the priority of the point density parameter, maximum density density[high] maxPointCount > interval > density > control parameters in the DQL statement

1. Common Query Notes

2. Unrecovered Events Query

3. OpenAPI Cross-Site Data Query

Note: When querying data through the OpenAPI interface, the default role is Administrator. Note that Data Access rules may apply.

Request Example¶

curl 'https://openapi.guance.com/api/v1/df/asynchronous/query_data' \
-H 'Content-Type: application/json' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-raw '{"queries":[{"qtype":"dql","query":{"q":"L::re(`.*`):(`message`)","timeRange":[1772516130000,1772519730000],"limit":100}}]}' \
--compressed

Response¶

{
    "code": 200,
    "content": {
        "data": [
            {
                "async_id": "async_task_id",
                "is_running": true
            }
        ]
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "TRACE-XXXX"
}