查询 - MoleSignal Docs

MoleSignal 暴露单一查询端点，底层是 DataFusion。可运行完整 SQL —— 包括 join、CTE、窗口函数 —— 或面向指标的 PromQL 子集，都针对同一存储。

查询端点

POST /api/v1/query
Authorization: Bearer <jwt>
Content-Type: application/json

请求体

字段	类型	必填	说明
`org_id`	string	✅	为请求兼容保留；实际以认证上下文中的组织为准。
`language`	string	✅	`sql` 或 `promql`。
`statement`	string	✅	查询文本。
`time_range`	object	✅	`{ "start": <微秒>, "end": <微秒> }` —— Unix 纪元起微秒。
`stream`	object	—	`{ "name": "app", "stream_type": "logs" }`；可查询信号类型为 `logs`、`metrics`、`traces` 和 `profiles`。
`limit`	integer	—	行数上限。

响应

响应包含 columns、数组形态的 rows、scanned_rows 与 took_ms。联邦查询响应还可能包含 federation 元数据。

发送 Accept: application/x-ndjson 可逐行返回对象，并在最后附上 __meta__ 记录。流式会绕过结果缓存。

SQL

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(*) FROM app WHERE _timestamp > 0 GROUP BY level\",
       \"time_range\":{\"start\":0,\"end\":2000000000000000},
       \"stream\":{\"name\":\"app\",\"stream_type\":\"logs\"}}"

由于日志、指标、追踪同处一个存储，可在一条查询里跨信号 join —— 例如按 trace_id 把错误日志和对应 span 关联起来：

SELECT l.msg, t.duration_ms
FROM app AS l
JOIN spans AS t ON l.trace_id = t.trace_id
WHERE l.level = 'error'

PromQL

设 language: "promql" 即可对指标流运行 PromQL。instant 与 range 查询均支持（range 按 [start, end] 步进、输出 matrix）。覆盖面很广——rate 家族与全部 *_over_time、标准聚合（含 topk / limitk）、histogram_quantile、label_replace / label_join、数学与三角、集合运算 and / or / unless 配 on / ignoring + group_left / group_right 向量匹配、选择器 @ / offset，以及子查询。

{
  "org_id": "<org>",
  "language": "promql",
  "statement": "histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket[5m])))",
  "time_range": { "start": 0, "end": 2000000000000000 }
}

PromQL 支持矩阵

支持的函数、运算符、修饰符完整清单，以及已知差异（native-histogram 函数、二元 default）。

事件上下文（search around）

要拉取某条事件前后各 N 条（日志上下文视图），用 POST /api/v1/query/search_around，传 event_timestamp_us、stream、stream_type，以及可选的 before / after（各默认 50）。

异步、检查与取消

给 POST /api/v1/query 加 Prefer: respond-async，或直接提交到 POST /api/v1/query/jobs，可创建持久化搜索任务。
GET /api/v1/query/jobs/{id} 返回状态，/results 返回完成后的结果。
POST /api/v1/query/inspect 只做规划不执行，返回查询元数据与当前可用的逻辑计划。
POST /api/v1/query/recommendations 不执行查询，只分析查询画像。
GET /api/v1/query/running 与 POST /api/v1/query/{id}/cancel 供组织管理员查看和取消活动查询。

普通查询需要 streams.query；活动查询管理分别需要 org.settings.read 或 org.settings.manage。

联邦搜索

Enterprise Edition 可给查询端点添加 ?clusters=local,cluster-name。只要包含非本地目标，就需要 federated_search 授权。无法访问的远端会在 federation 元数据中标为 degraded，不会被静默当成本地数据。

缓存

查询经过三级缓存 —— file_meta、parquet_meta、query_result —— 外加默认启用的 parquet 磁盘缓存（./data/cache/parquet，10 GB LRU）。缓存对响应契约透明，请通过服务器指标观察缓存行为。

快速上手

观察

可靠性

AI 运维

数据

协作

管理

部署与运维

查询

查询端点

请求体

响应

SQL

PromQL

PromQL 支持矩阵

事件上下文（search around）

异步、检查与取消

联邦搜索

缓存

​查询端点

​请求体

​响应

​SQL

​PromQL

PromQL 支持矩阵

​事件上下文（search around）

​异步、检查与取消

​联邦搜索

​缓存

查询端点

请求体

响应

SQL

PromQL

事件上下文（search around）

异步、检查与取消

联邦搜索

缓存