Query planning

PulsusDB treats query behavior as the input to schema design. The planner aims to read the smallest correct set of rows, push safe work into ClickHouse, and preserve the source language’s semantics.

Planning stages

PulsusDB pushes safe work into ClickHouse and completes residual language semantics in Rust.

Parse and validate

Each front end produces a typed representation of LogQL, PromQL, or TraceQL. It rejects unsupported syntax and applies query budgets before expensive work begins.

Resolve labels first

Selectors use index tables to produce candidate fingerprints. The planner bounds these intermediate sets to prevent a broad matcher from creating unbounded fan-out.

Choose raw or rollup data

For metrics and exact log aggregates, the planner can choose a rollup whose resolution fits the query range and step. It falls back to a finer level or raw data when a rollup would change the answer.

Lower safe work

Time filters become PREWHERE. Label, attribute, and line filters are pushed only when ClickHouse can reproduce the source language’s semantics. Partial aggregation runs on shards where possible.

Finalize in Rust

Operations that cannot be expressed faithfully in ClickHouse remain in the Rust evaluation layer. The result should be complete or return a named limit error; broad aggregates must not be silently truncated.

Explain a query

Send the optional header:

X-Pulsus-Explain: 1

The response can expose planner stages, generated SQL, and routing information. Use this while diagnosing unexpected reads or rollup choices; avoid enabling it indiscriminately in public clients because query plans can contain operational details.

Example

LogQL

{service_name="checkout"} |= "timeout"

A typical plan:

1. resolve service_name="checkout" through the log stream index;
2. bound the scan to the request interval and matching fingerprints;
3. use a text/skip index for the line term when eligible;
4. order and limit the selected entries;
5. format the product-neutral logs response.