Selectors and filters
Match streams by label and filter lines with familiar LogQL syntax. Whole words can use the index; substrings cannot
The LogQL query layer for ClickHouse® software
LogQL
On ClickHouse® software
Keep the selectors, filters, pipelines and aggregations your teams already know while PulsusDB translates LogQL into read plans for ClickHouse® software
logql.queryLOGS
LogQL
{service_name="checkout"} |= "timeout"PLAN↓index + time pruning
CLICKHOUSE SQL
SELECT ts, labels, body
FROM log_samples
PREWHERE ts BETWEEN $start AND $end
AND fingerprint IN (…)
WHERE body LIKE '%timeout%'
ORDER BY ts DESC LIMIT 100
Streams, metrics or live tailX-Pulsus-Explain: 1
A familiar language with a different read path
Resolve streams first Index whole words
PulsusDB treats the read path as part of the schema. Label indexes narrow the stream set and word indexes prune filters with indexable terms. Substring-only filters still scan those selected streams, while the query engine handles the LogQL pipeline and response shape
Pipelines and metrics
Parse structured lines, transform labels, unwrap values and aggregate log-derived metrics
Search and live tail
Use range and instant queries, label and series discovery, index stats and WebSocket live tail
Loki compatibility
Enable flag-gated Loki query aliases when an existing datasource needs the familiar endpoint surface
From selector to compiled plan
See the query
See the SQL
Move from a simple selector to a complex expression and inspect the representative ClickHouse SQL shape PulsusDB produces at each level
01Simple LogQL
Select one log stream
The label selector is resolved first, so the sample scan starts with a small set of fingerprints instead of reading every log line
LOGQLRange query · newest 100 lines
{service_name="checkout"} PLAN STAGES
- 01label index
- 02stream fingerprints
- 03time pruning
CLICKHOUSE SQLREPRESENTATIVE PLAN
SELECT fingerprint
FROM log_streams_idx
WHERE key = 'service_name' AND val = 'checkout'
GROUP BY fingerprint;
SELECT fingerprint, timestamp_ns, body, structured_metadata
FROM log_samples
PREWHERE service IN ('checkout')
WHERE fingerprint IN ({resolved_streams})
AND timestamp_ns > {start} AND timestamp_ns <= {end}
ORDER BY timestamp_ns DESC, fingerprint DESC
LIMIT 10002Composed LogQL
Filter the selected streams
A line filter becomes a ClickHouse predicate after stream resolution. The body index can prune granules for indexable terms before matching rows are returned
LOGQLRange query · whole-word search term
{service_name="checkout"} |= "timeout" PLAN STAGES
- 01stream resolution
- 02word-index pruning
- 03stable keyset order
CLICKHOUSE SQLREPRESENTATIVE PLAN
SELECT fingerprint, timestamp_ns, body, structured_metadata
FROM log_samples
PREWHERE service IN ('checkout')
WHERE fingerprint IN ({resolved_streams})
AND timestamp_ns > {start} AND timestamp_ns <= {end}
AND body LIKE '%timeout%'
ORDER BY timestamp_ns DESC, fingerprint DESC,
cityHash64(body) DESC, body DESC
LIMIT 10003Complex LogQL
Parse, reshape and aggregate
One LogQL expression pipes raw-line filters into JSON parsing, an extracted-field filter, derived labels, a rewritten line and a final regex before aggregating the surviving logs by route
LOGQLMetric query · eight ordered pipeline stages · derived grouping
sum by (route) (
count_over_time(
{env="prod", service_name=~"checkout|payments"}
|= "request"
!= "health"
|~ `"status":5..`
| json
| status >= 500
| label_format route="{{.method}} {{.path}}"
| line_format "{{.status}} {{.message}}"
|~ `5.. .*timeout`
[5m]
)
) PLAN STAGES
- 01resolve streams and time
- 02push raw-line predicates
- 03run the ordered residual pipeline
CLICKHOUSE SQLREPRESENTATIVE PLAN
-- 1. Resolve the two-label stream intersection
SELECT fingerprint
FROM log_streams_idx
WHERE (key = 'env' AND val = 'prod')
OR (key = 'service_name'
AND match(val, '(?-s)^(?:checkout|payments)$'))
GROUP BY fingerprint
HAVING countDistinct(key) = 2;
-- 2. Push filters that still reference the stored body
SELECT fingerprint, timestamp_ns, body, structured_metadata
FROM log_samples
PREWHERE service IN ('checkout', 'payments')
WHERE fingerprint IN ({resolved_streams})
AND timestamp_ns > {start} AND timestamp_ns <= {end}
AND body LIKE '%request%'
AND NOT (body LIKE '%health%')
AND match(body, '"status":5..')
ORDER BY timestamp_ns ASC, fingerprint ASC;
-- 3. PulsusDB preserves the ordered residual pipeline
-- json -> status filter -> label_format -> line_format
-- -> rewritten-line regex -> count_over_time -> sum by (route) SQL is shortened for readability and uses named placeholders Read the query lowering reference ↗
From expression to efficient read
Plan the query
Protect the answer
PulsusDB only pushes work into the ClickHouse database when it can preserve the language’s semantics. Everything else remains the query engine’s job
01
RESOLVEStart with labels
Turn the stream selector into a bounded set of fingerprints before scanning log bodies
→02
PRUNEUse the word index
Prune indexable word searches in the ClickHouse database while leaving substring-only matching on the bounded stream scan
→03
PIPELINEFinish LogQL faithfully
Evaluate parsers, transformations and aggregations that belong in the query engine
Product-neutral by default
The API surface
your tools need
Use PulsusDB’s documented API directly. Compatibility aliases remain optional, so the platform is not defined by another product’s routing conventions
See the compatibility matrix ↗GET
/api/logs/v1/query_rangeRange queryGET
/api/logs/v1/queryInstant queryWS
/api/logs/v1/tailLive tail