POST /api/v1/query
GET /api/v1/query
streams.query，系统遥测则需要 sys.telemetry.read。
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
org_id | string | 是 | 必须存在，但值会被忽略，生效的是已认证的组织。 |
language | string | 是 | sql 或 promql。 |
statement | string | 是 | 查询语句。 |
time_range | object | 是 | { "start": <微秒>, "end": <微秒> }。 |
stream | object | SQL 必填 | { "name": "app", "stream_type": "logs" } 指明主表，两个字段都必填，类型为 logs、metrics、traces、profiles 或 extend。 |
limit | integer | 否 | 行数上限。 |
GET /api/v1/query 在查询字符串中接收同样的查询，因此一次读取就是一个可以复制、再次打开的地址。它的响应、支持的请求头和所需权限都与 POST 相同。语句太长、放不进地址时请用 POST 发送：服务前面的代理可能拒绝超过 8 KB 的请求行。
| 参数 | 必填 | 说明 |
|---|---|---|
language | 是 | sql 或 promql。 |
statement | 是 | 查询语句，需要 URL 编码。 |
start、end | 是 | 以微秒表示的时间范围。 |
stream、stream_type | SQL 必填 | 主表及其类型，需要同时给出。 |
limit | 否 | 行数上限。 |
| 名称 | 效果 |
|---|---|
Prefer: respond-async | 总是创建搜索任务并返回 202。 |
Prefer: respond-sync | 在请求内运行，即使时间范围很长。 |
Accept: application/x-ndjson | 逐行流式返回 JSON 对象，最后附带一条 {"__meta__": ...} 记录。 |
?clusters=local,remote | 在联邦搜索中包含远程集群。 |
NOW=$(date +%s)000000
curl -X POST http://localhost:5080/api/v1/query \
-H "authorization: Bearer $MS_JWT" \
-H 'content-type: application/json' \
-d "{\"org_id\":\"$MS_ORG\",\"language\":\"sql\",
\"statement\":\"SELECT level, count(*) AS n FROM app GROUP BY level\",
\"time_range\":{\"start\":$((NOW-3600000000)),\"end\":$((NOW+60000000))},
\"stream\":{\"name\":\"app\",\"stream_type\":\"logs\"}}"
NOW=$(date +%s)000000
curl -G http://localhost:5080/api/v1/query \
-H "authorization: Bearer $MS_JWT" \
--data-urlencode 'language=promql' \
--data-urlencode 'statement=sum(rate(http_requests_total[5m]))' \
--data-urlencode "start=$((NOW-3600000000))" \
--data-urlencode "end=$NOW"
{
"columns": ["level", "n"],
"rows": [["error", 12], ["info", 40]],
"scanned_rows": 10432,
"took_ms": 18
}
[querier].auto_async_threshold_rows 的查询会返回 202：
{
"job_id": "3KE1WD4SrFXhyftdMJY0FN7fTFj",
"monitor": "/api/v1/query/jobs/3KE1WD4SrFXhyftdMJY0FN7fTFj",
"state": "pending"
}
| 状态码 | 原因 |
|---|---|
400 | 语句无法规划，SQL 缺少 stream 提示（query.stream hint is required），或查询读取的行数超过 [querier].max_scan_rows 的限制。GET 缺少必填参数，或给了 stream 而没有 stream_type 时，也返回 400。 |
503 | 在分角色集群中，没有存活的 querier 节点（no querier node is available）。 |
403 | 组织中不存在该数据流（stream not found: <name>），或 Token 缺少 streams.query。 |
422 | 请求体字段缺失或类型错误，例如 org_id 或 stream_type，响应为纯文本。 |