DQL 数据异步查询¶

POST /api/v1/df/asynchronous/query_data

概述¶

Body 请求参数¶

参数补充说明¶

查询说明

本接口同时支持 POST 和 GET，两种方式使用相同的 JSON object 参数结构：POST 将完整参数放在 application/json request body；GET 在 query string 中通过 body=<完整 JSON object 字符串> 传递并进行 URL 编码。顶层不接受 string、array、null、number 或 boolean。

异步查询最终响应的 content.data[i].warnings[] 可能包含 DQLDataAccessScopeRestricted。details[0].metadata.namespace 本期固定为 logging；restriction=partial 表示仅返回有权限索引的数据， restriction=all 表示相关日志索引均无权限并返回空结果。HTTP 状态码和请求参数不变。

async_id 生命周期（重要）

1. 发起一个新的逻辑查询时，必须省略 queries[i].async_id。服务端若转为异步执行，会在同一位置返回 content.data[i].is_running=true 和非空 content.data[i].async_id。
2. 仅当 is_running 严格等于 true 且 async_id 非空时，才使用该 ID 轮询同一任务。轮询请求应保持该项的 qtype、query、目标工作空间及 targetRegion 不变，并把 ID 放回对应的 queries[i].async_id。
3. 当 is_running=false 时，本次任务已结束；即使响应结构里仍出现 async_id 字段，调用方也不得在下一次新查询中继续携带旧 ID。新查询、修改过查询语句/时间范围的查询都必须再次省略 async_id。
4. async_id 只属于一个查询项和一次任务，不是会话 ID，也不是分页游标。批量查询时，content.data[i] 与 queries[i] 按数组下标对应，禁止把一个查询项的 ID 用到另一个查询项。为降低映射错误，异步调用建议每次只提交一个 query。
5. 如果 is_running=true 但 async_id 为空，视为不可轮询的异常响应；不要填入历史 ID，应记录 traceId 并按有限重试策略重新发起该逻辑查询或联系技术支持。

建议采用递增退避并设置总超时，避免无间隔轮询。任务完成后，如需翻页，应使用最终结果返回的 search_after、next_cursor_time 或 next_cursor_token，不要使用 async_id 代替分页参数。

首次请求（不传 async_id）

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

仅在运行中时轮询同一任务

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

跨站点查询还需遵守“一个请求只查询一个 targetRegion”的限制。目标工作空间与站点编码的获取及完整调用流程参考：OpenAPI 跨站点数据查询。

1、 参数说明

2、 queries[*]成员参数结构说明

与同步查询相比，每个 query 项额外支持 async_id；它只用于轮询当前仍在运行的任务。

3、 响应点密度density 参数值说明

• 注意点密度参数的优先级，最大密度density[high] * maxPointCount > interval > density > dql 语句中的控制参数

4、 常见查询说明

• 未恢复事件查询
• OpenAPI 跨站点数据查询 注: openapi 接口进行数据查询时, 默认为 管理员 角色. 需注意可能受到 数据访问规则限制

请求例子¶

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

响应¶

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