Querying

MoleSignal exposes a single query endpoint backed by DataFusion. The endpoint supports full SQL — including joins, CTEs, and window functions — or a PromQL subset for metrics, all against the same store.

The query endpoint

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

Request body

Field	Type	Required	Notes
`org_id`	string	✅	Retained in the body for compatibility; the authenticated organization is authoritative.
`language`	string	✅	`sql` or `promql`.
`statement`	string	✅	The query text.
`time_range`	object	✅	`{ "start": <microseconds>, "end": <microseconds> }` — microseconds since epoch.
`stream`	object	—	`{ "name": "app", "stream_type": "logs" }`; queryable signal types are `logs`, `metrics`, `traces`, and `profiles`.
`limit`	integer	—	Row cap.

Response

The response carries columns, array-shaped rows, scanned_rows, and took_ms. Federated responses may also carry federation metadata.

Send Accept: application/x-ndjson to stream objects row-by-row, followed by a __meta__ record. Streaming bypasses the result cache.

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

Because logs, metrics, and traces live in the same store, one query can join across signals — for example, join error logs to matching spans on trace_id:

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

Set language: "promql" to run PromQL over metric streams. Both instant and range queries are supported (range steps through [start, end] and returns a matrix). Coverage is broad — the rate family and all *_over_time, the standard aggregations (incl. topk / limitk), histogram_quantile, label_replace / label_join, math & trig, the and / or / unless set operators with on / ignoring + group_left / group_right matching, selector @ / offset, and subqueries.

{
  "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 support matrix

The full list of supported functions, operators, and modifiers — plus the known gaps (native-histogram functions, the binary default fill-in).

Search around an event

To pull the N events immediately before and after a given one (log context view), use POST /api/v1/query/search_around with event_timestamp_us, stream, stream_type, and optional before / after counts (default 50 each).

Async, inspection, and cancellation

Add Prefer: respond-async to POST /api/v1/query, or submit directly to POST /api/v1/query/jobs, for a durable search job.
GET /api/v1/query/jobs/{id} reports state; /results returns completed output.
POST /api/v1/query/inspect plans without executing and returns query metadata and the available logical plan.
POST /api/v1/query/recommendations analyzes a query profile without executing the query.
GET /api/v1/query/running and POST /api/v1/query/{id}/cancel let organization administrators inspect and cancel active work.

Standard queries require streams.query. Active-query administration requires org.settings.read or org.settings.manage.

Federated search

Enterprise Edition can add ?clusters=local,cluster-name to the query endpoint. Any non-local target requires the federated_search entitlement. Unreachable remotes are represented as degraded clusters in federation metadata instead of silently becoming local data.

Caching

Queries flow through a 3-level cache — file_meta, parquet_meta, and query_result — plus a parquet disk cache enabled by default (./data/cache/parquet, 10 GB LRU). Caching is transparent to the response contract; use server metrics to measure cache behavior.

Getting Started

Observe

Reliability

AI Ops

Data

Collaboration

Admin

Deploy & Operate

The query endpoint

Request body

Response

SQL

PromQL

PromQL support matrix

Search around an event

Async, inspection, and cancellation

Federated search

Caching

​The query endpoint

​Request body

​Response

​SQL

​PromQL

PromQL support matrix

​Search around an event

​Async, inspection, and cancellation

​Federated search

​Caching

The query endpoint

Request body

Response

SQL

PromQL

Search around an event

Async, inspection, and cancellation

Federated search

Caching