DQL 数据查询(旧版)¶
POST /api/v1/df/query_data
概述¶
DQL 数据查询
Query 请求参数¶
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| body | string | dql 查询 query 结构体 允许为空: False |
|
| queries_body | string | dql 查询 query 结构体(2023-08-11日下架该参数) 允许为空: False |
|
| search_after | string | 分页查询请求参数(2023-08-11日下架该参数) 允许为空: False |
参数补充说明¶
查询说明
本接口为旧版兼容入口。新接入建议使用 POST /api/v1/df/query_data_v1；旧版 GET
继续使用 body=<URL 编码后的 JSON> 传参，不要对 JSON 进行二次编码。
本接口同时支持 POST 和 GET，两种方式使用相同的 JSON object 参数结构：
- POST：完整参数作为
application/jsonrequest body 传递； - GET：不使用 HTTP entity body，在 query string 中通过
body=<完整 JSON object 字符串>传递， 客户端应对body参数做 URL 编码； - 顶层必须是 JSON object，不接受双重 JSON 编码后的 string、array、null、number 或 boolean。
跨工作空间/跨站点查询时，一个请求中的所有 queries[*] 只能指向同一个
targetRegion。需要查询多个站点时，应按站点拆分请求并在客户端合并结果。
目标工作空间和 targetRegion 应通过 /api/v1/wksp_share/granted_ws_list 获取，
具体参考：OpenAPI 跨站点数据查询。
响应 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 共存。
1、 查询字符串 元素字段说明
| 参数名 | type | 必选 | 说明 |
|---|---|---|---|
| body | string | 与 queries_body 二选一 | 查询请求体 |
| queries_body[*] | string | 与 body 二选一 | (旧版参数，2023-08-10 日下架) 查询列表 |
| search_after | string | (旧版参数，2023-08-10 日下架, 新版参数位置挪移至 query 结构体中) 查询分页数据. 首次查询默认为[], 需要查询更多分页数据时,将上次查询结果中的 search_after 字段加上,用于查询后续数据 |
body 与兼容参数 queries_body 均为条件必填参数，请至少提供一个非空且合法的 JSON 值；同时提供时优先使用非空的 queries_body。
2、 body 中 JSON 结构参数说明
| 参数名 | type | 必选 | 说明 |
|---|---|---|---|
| queries | array | Y | 多命令查询，其内容为 query 对象组成的列表 |
| fieldTagDescNeeded | boolean | 是否需要 field 或者 tag 描述信息 |
3、 queries[*]成员参数结构说明
| 参数名 | type | 必选 | 说明 |
|---|---|---|---|
| qtype | string | Y | 查询语句的类型 dql: DQL 查询语句；promql: PromQL 查询语句 |
| query | json | Y | 查询结构 |
| query.q | string | 与 qtype 类型保持一致的 查询语句，例如 dql 或者 promql 查询语句 | |
| query.ignore_cache | boolean | 是否禁用缓存，默认 false，表示使用缓存 |
|
| query.promqlType | enum | qtype=promql 时生效，可选值 instantQuery、rangeQuery，默认 rangeQuery |
|
| query.highlight | boolean | 是否显示高亮数据 | |
| query.timeRange | array | 时间范围的时间戳列表；DQL / PromQL 的起止时间须使用相同单位（秒、毫秒、微秒或纳秒），混用时返回 HTTP 400 ft.TimeRangeUnitMismatch；分页游标保持独立 |
|
| query.disableMultipleField | bool | 是否打开单列模式，默认为 true |
|
| query.showLabel | bool | 是否显示对象的 labels，默认 false |
|
| query.funcList | array | 再次聚合修饰 DQL 返回值；disableMultipleField=false 时当前参数无效 |
|
| query.slimit | integer | 时间线分组大小，只针对指标查询有效 | |
| query.soffset | integer | 时间线分组偏移量 | |
| query.limit | integer | 分页大小 | |
| query.offset | integer | 分页偏移量 | |
| query.orderby | array | 排序列表，结构为 {fieldName: method}；指标集查询只支持 fieldName=time，method 可选 desc、asc |
|
| query.density | string | 响应的点密度, 优先级小于 autoDensity 且大于 dql 语句中设置的密度 | |
| query.interval | number | 时间分片间隔，只接受可转换为 Kodo int64 范围内且不小于 1ms 整数毫秒的正数；默认单位为秒，可通过 interval_unit 指定为毫秒 | |
| query.interval_unit | string | interval 的单位，可选 s、ms，默认 s |
|
| query.search_after | array | 分页标记, 由当前接口返回的分页标记，用于下一次请求时传入 | |
| query.maxPointCount | integer | 最大点数 | |
| query.workspaceUUID | string | 要查询的单个授权方工作空间 UUID；* 表示查询 targetRegion 内全部已授权空间 |
|
| query.workspaceUUIDs | array | 要查询的授权方工作空间 UUID 列表；非空时优先于 query.workspaceUUID。同一列表必须属于同一个站点；["*"] 表示查询 targetRegion 内全部已授权空间。建议不要同时传两个字段 |
|
| query.targetRegion | string | 授权方工作空间所属站点的 regionCode；从 /wksp_share/granted_ws_list 中与目标 workspaceUUID 同组的 regionCode 获取。显式跨站点查询建议传入，查询 * 时必须传入 |
|
| query.output_format | string | lineprotocol: 行协议输出，默认不填的话，默认保持现有输出格式不变 | |
| query.cursor_time | integer | 分段查询阈值：第一次分段查询时设置为 end_time；之后传入响应中的 next_cursor_time |
|
| query.cursor_token | string | 分页查询 token(由引擎返回 cursor_token 的值): 分页查询时，需要将上次查询返回的 next_cursor_token 设置为本次查询的 cursor_token；不带 cursor_token 的请求可能会造成翻页时相同时间戳的数据被跳过。 | |
| query.disable_sampling | bool | 采样禁用开关, 默认值为 false | |
| query.disable_truncate | bool | 是否禁用返回内容截断，默认 false，表示允许截断 |
4、 响应点密度density 参数值说明
| 可选值 | 说明 |
|---|---|
| lower | 较低，60个点 |
| low | 低，180个点 |
| medium | 中等，360个点 |
| high | 高，720个点 |
- 注意点密度参数的优先级，最大密度
density[high]* maxPointCount > interval > density > dql 语句中的控制参数
5、 常见查询说明
注: openapi 接口进行数据查询时, 默认为 管理员 角色. 需注意可能受到 数据访问规则限制
请求例子¶
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
响应¶
{
"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"
}