DQL 数据查询¶

POST /api/v1/df/query_data_v1

概述¶

DQL 数据查询

Body 请求参数¶

参数名	类型	必选	说明
queries	array		多命令查询，其内容为 query 对象组成的列表；业务调用应至少传入一个 query，接口暂兼容空数组或缺省并返回空数据允许为空: False
fieldTagDescNeeded	boolean		是否需要 field 或者 tag 描述信息，默认 false 允许为空: False

参数补充说明¶

查询说明

本接口同时支持 POST 和 GET，两种方式使用相同的 JSON object 参数结构：

POST：完整参数作为 application/json request body 传递；
GET：不使用 HTTP entity body，在 query string 中通过 body=<完整 JSON object 字符串> 传递，客户端应对 body 参数做 URL 编码；
顶层必须是 JSON object，不接受双重 JSON 编码后的 string、array、null、number 或 boolean。

响应 content.data[i].warnings[] 可能包含 DQLDataAccessScopeRestricted：

details[0].metadata.namespace 本期固定为 logging；
details[0].metadata.restriction=partial 表示仅返回有权限日志索引的数据；
details[0].metadata.restriction=all 表示相关日志索引均无数据访问权限并返回空结果；
HTTP 状态码仍为 200，warning 与 GuanceDB/Kodo 已有 warning 共存。

可选参数的默认值表示“调用方省略该参数”时的行为：

query.timeRange 不传时，Studio 向下游传递 time_range: []，不会在 Studio 侧补固定时间窗口，也不会覆盖 DQL 语句内的时间范围。当前普通 DQL Select 主链路由 GuanceDB v1.52.0 兜底查询最近 30 分钟；该值属于下游实现，不是所有 qtype、所有存储引擎的统一 OpenAPI 默认值。PromQL 查询要求显式提供两个时间点。为保证跨版本、跨引擎行为一致，建议显式传入 [startTimeMs, endTimeMs] 两个毫秒时间戳。
query.limit、query.slimit、排序、最大点数和查询时间上限会受到 DQL 语句、下游服务配置及存储引擎影响，没有统一的 OpenAPI 固定默认数值；调用方需要稳定边界时应显式传入。

跨工作空间/跨站点查询约束：

一个请求中的所有 queries[*] 只能指向同一个 targetRegion；需要查询多个站点时，按站点拆分请求并在客户端合并结果。
非空 workspaceUUIDs 优先于 workspaceUUID；当 workspaceUUIDs 为空数组或 null 时会回退使用 workspaceUUID。建议不要同时传两个字段。当前工作空间查询可省略两者；显式查询授权空间时建议同时传入该授权空间所属的 targetRegion。
workspaceUUIDs=["*"] 时无默认值的参数是 targetRegion；查询所有授权空间时必须显式传入 targetRegion。兼容写法 workspaceUUID="*" 保持支持，并遵循相同规则。
目标工作空间和 targetRegion 应通过 /api/v1/wksp_share/granted_ws_list 获取。完整示例参考：OpenAPI 跨站点数据查询。

1、参数说明

参数名	type	必选	默认值 / 省略行为	说明
queries	array		`[]`（返回空数据）	多命令查询，其内容为 query 对象组成的列表；业务查询应至少传入一个 query
fieldTagDescNeeded	boolean		`false`	是否需要 field 或者 tag 描述信息

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

参数名	type	必选	默认值 / 省略行为	说明
qtype	string		`dql`	查询语句的类型 `dql`: 表示 DQL 类型查询语句； `promql`: 表示 PromQL 类型查询语句
query	json	Y	-	有效查询必需；缺失或 `query.q` 为空不会形成有效的下游查询
query.q	string		空字符串（通常不会形成有效查询）	与 qtype 类型保持一致的查询语句，例如 DQL 或 PromQL 查询语句
query.ignore_cache	boolean		`false`	是否禁用缓存；`false` 表示使用缓存
query.promqlType	enum		`rangeQuery`	qtype=promql 时生效，可选值为 `instantQuery`、`rangeQuery`
query.highlight	boolean		`false`	是否显示高亮数据
query.timeRange	array		`[]`	外部时间范围；DQL 不传时不覆盖语句内窗口，当前普通 Select 主链路由 GuanceDB 兜底最近 30 分钟；PromQL 必须显式传入两个时间点，其他引擎行为可能不同；DQL / PromQL 的起止时间须使用相同单位（秒、毫秒、微秒或纳秒），混用时返回 HTTP 400 `ft.TimeRangeUnitMismatch`；分页游标保持独立
query.disableMultipleField	bool		`true`	是否打开单列模式
query.showLabel	bool		`false`	是否显示对象的 labels
query.funcList	array		`[]`	再次聚合修饰 DQL 返回值；`disableMultipleField=false` 时当前参数无效
query.slimit	integer		DQL / 下游配置决定	时间线分组大小，只针对指标查询有效
query.soffset	integer		DQL 中的值；DQL 也未设置时无额外偏移	时间线分组偏移量；当前解析器仅用正数外部值补齐 DQL 未设置的偏移，`0` 不会清除 DQL 已有值
query.limit	integer		DQL / 下游配置决定	分页大小
query.offset	integer		DQL 中的值；DQL 也未设置时无额外偏移	分页偏移量；当前解析器仅用正数外部值补齐 DQL 未设置的偏移，`0` 不会清除 DQL 已有值
query.orderby	array		DQL / 查询引擎决定	排序列表，结构为 `{fieldName: method}`；指标集查询只支持 fieldName=time，method 可选 `desc`、`asc`
query.sorderby	array		DQL / 查询引擎决定	排序列表；column 支持返回单个值的聚合函数，例如 min、max、last、avg、p90、p95、count
query.order_by	array		DQL / 查询引擎决定	Doris 引擎兼容排序列表，结构为 `[{"column": "field", "order": "DESC"}]`
query.sorder_by	array		DQL / 查询引擎决定	Doris 引擎兼容时间线排序列表，结构为 `[{"column": "field", "order": "DESC"}]`
query.density	string		DQL / 查询引擎决定	响应点密度，优先级高于 DQL 语句中的控制参数
query.interval	number		DQL / 查询引擎决定	时间分片间隔，只接受可转换为 Kodo int64 范围内且不小于 1ms 的整数；单位由 `interval_unit` 指定
query.interval_unit	string		`s`	interval 的单位，可选 `s`、`ms`
query.align_time	boolean		`false`	是否按查询引擎时间网格对齐时间分片
query.tz	string		`Asia/Shanghai`	查询时区
query.search_after	array		不设置分页标记	深度分页参数；下一次请求应传入上一次响应中的 `search_after`
query.maxPointCount	integer		DQL / 查询引擎决定	最大点数
query.workspaceUUID	string		当前工作空间	要查询的单个授权方工作空间 UUID；`*` 表示查询 `targetRegion` 内全部已授权空间
query.workspaceUUIDs	array		不设置	要查询的授权方工作空间 UUID 列表；非空时优先于 `query.workspaceUUID`。同一列表必须属于同一个站点；`["*"]` 表示查询 `targetRegion` 内全部已授权空间。建议不要同时传两个字段
query.targetRegion	string		当前工作空间查询隐含当前站点；查询所有授权空间时无默认值	授权方工作空间所属站点的 `regionCode`；从 `/wksp_share/granted_ws_list` 中与目标 `workspaceUUID` 同组的 `regionCode` 获取。显式跨站点查询建议传入，查询所有授权空间时必须显式传入；兼容写法 `workspaceUUID="*"` 遵循相同规则
query.output_format	string		现有 JSON 响应格式	设置为 `lineprotocol` 时返回行协议
query.cursor_time	integer		不设置游标	第一次分段查询时设置为 end_time；之后传入响应中的 `next_cursor_time`
query.cursor_token	string		不设置 token	分页时传入上一次响应中的 `next_cursor_token`；不传可能导致相同时间戳的数据在翻页时被跳过
query.disable_sampling	bool		`false`	是否禁用采样
query.disable_truncate	bool		`false`	是否禁用返回内容截断；`false` 表示允许截断

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

可选值	说明
lower	较低，60个点
low	低，180个点
medium	中等，360个点
high	高，720个点

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

4、常见查询说明

未恢复事件查询
OpenAPI 跨站点数据查询

注: openapi 接口进行数据查询时, 默认为管理员角色. 需注意可能受到数据访问规则限制

5、请求 JSON 格式错误

当请求体不是合法 JSON 时，接口在进入查询处理前返回 HTTP 400，errorCode 为共享错误码 ft.RequestJsonFormatError。content.reason、content.line、content.column 分别表示 JSON 解析原因、行号和列号；响应不会回显原始请求体。

{
  "code": 400,
  "content": {
    "reason": "Expecting property name enclosed in double quotes",
    "line": 22,
    "column": 17
  },
  "errorCode": "ft.RequestJsonFormatError",
  "message": "请求 JSON 格式错误",
  "success": false,
  "traceId": "TRACE-..."
}

请求例子¶

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

curl --get '<Endpoint>/api/v1/df/query_data_v1' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode 'body={"queries":[{"qtype":"dql","query":{"q":"M::`cpu`:(avg(`usage_idle`))"}}]}' \
--compressed

响应¶

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

DQL 数据查询¶

概述¶

Body 请求参数¶

参数补充说明¶

请求例子¶

响应¶

文档内容是否对您有帮助？ ×

文档内容是否对您有帮助？