Standard query API
Use instant and range queries, labels, series, metadata and exemplar endpoints through the Prometheus HTTP API
Prometheus language and API with ClickHouse® software
Keep PromQL
Change the engine
Run the metrics queries, dashboards and ad hoc analysis your team already knows while PulsusDB plans the read path across raw samples and ClickHouse® rollups
promql.queryMETRICS
PromQL
sum by (service) (rate(http_requests_total[5m]))PLAN↓index + time pruning
CLICKHOUSE SQL
SELECT service,
toStartOfInterval(ts, 60) AS bucket,
sum(value) AS samples
FROM metric_samples
PREWHERE metric_name = 'http_requests_total'
GROUP BY service, bucket
Prometheus response semanticsX-Pulsus-Explain: 1
A familiar language with a different read path
Prometheus on the outside ClickHouse database underneath
PulsusDB exposes the standard Prometheus HTTP API for metrics. It resolves series, chooses the right raw or rollup source, pushes exact work into the ClickHouse database and evaluates the remaining PromQL semantics in its own engine
PromQL semantics
Selectors, vector matching, subqueries, aggregations and functions retain Prometheus query behaviour
Resolution-aware reads
Eligible range selectors use the appropriate ClickHouse rollup while the response grid still follows the requested range
Explain the plan
X-Pulsus-Explain reveals generated SQL, planner stages and whether raw samples or a rollup served the query
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 PromQL
Fetch one series set
An instant vector selector resolves matching labels to fingerprints, then reads only those series from the metric sample table
PROMQLInstant query · 5 minute lookback
up{job="api"} PLAN STAGES
- 01label resolution
- 02time pruning
- 03series pruning
CLICKHOUSE SQLREPRESENTATIVE PLAN
SELECT fingerprint, unix_milli, value
FROM metric_samples
PREWHERE metric_name = 'up'
WHERE unix_milli > {eval_time - lookback}
AND unix_milli <= {eval_time}
AND fingerprint IN (101, 205, 990)
ORDER BY fingerprint, unix_milli02Composed PromQL
Rate then aggregate
A selector, regular-expression matcher, range function and grouping expression become a narrow sample read before PromQL semantics finish in the stateless engine
PROMQLRange query · 5 minute rate window
sum by (service) (rate(http_requests_total{status=~"5.."}[5m])) PLAN STAGES
- 01regex matcher
- 02fingerprint semi-join
- 03sample window
CLICKHOUSE SQLREPRESENTATIVE PLAN
SELECT fingerprint, unix_milli, value
FROM metric_samples
PREWHERE metric_name = 'http_requests_total'
WHERE unix_milli > {start - 300000 - lookback}
AND unix_milli <= {end}
AND fingerprint IN (
SELECT fingerprint FROM metric_series
WHERE metric_name = 'http_requests_total'
AND match(JSONExtractString(labels, 'status'), '(?-s)^(?:5..)$')
)
ORDER BY fingerprint, unix_milli03Complex PromQL
Detect sustained SLO burn
Two windows and four range-vector branches calculate error-budget burn per service. Vector matching keeps only services breaching the threshold in both windows, filtering out brief spikes
PROMQLMulti-window SLO query · four selector branches · vector matching
(
(
sum by (service) (rate(http_requests_total{env="prod",status=~"5.."}[6h]))
/
sum by (service) (rate(http_requests_total{env="prod"}[6h]))
) / 0.001 > 6
)
and on (service)
(
(
sum by (service) (rate(http_requests_total{env="prod",status=~"5.."}[30m]))
/
sum by (service) (rate(http_requests_total{env="prod"}[30m]))
) / 0.001 > 6
) PLAN STAGES
- 01four resolved series sets
- 02per-branch tier selection
- 03raw + rollup splice
CLICKHOUSE SQLREPRESENTATIVE PLAN
-- Representative 6h leaf; the 30m leaf remains on the raw tier
WITH resolved AS (
SELECT fingerprint, labels FROM metric_series
WHERE metric_name = 'http_requests_total'
AND JSONExtractString(labels, 'env') = 'prod'
AND ({branch} = 'total' OR
match(JSONExtractString(labels, 'status'), '(?-s)^(?:5..)$'))
), tiered AS (
SELECT fingerprint, toUnixTimestamp(ts) * 1000 AS unix_milli,
finalizeAggregation(argMinMergeState(first_value)) AS first_value,
finalizeAggregation(argMaxMergeState(last_value)) AS last_value
FROM metric_samples_1h
WHERE ts >= {start} AND ts < {raw_boundary}
AND fingerprint IN (SELECT fingerprint FROM resolved)
GROUP BY fingerprint, ts
UNION ALL
SELECT fingerprint, unix_milli, value, value
FROM metric_samples
PREWHERE metric_name = 'http_requests_total'
WHERE unix_milli >= {raw_boundary} AND unix_milli <= {end}
AND fingerprint IN (SELECT fingerprint FROM resolved)
)
SELECT tiered.*, resolved.labels
FROM tiered INNER JOIN resolved USING (fingerprint)
ORDER BY fingerprint, unix_milli 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
PARSEUnderstand the expression
Build a PromQL plan from the same selectors, modifiers and operators your dashboards already send
→02
PRUNEFind the smallest read
Resolve matching series, constrain the time window and select an eligible rollup where it remains exact
→03
EVALUATEPreserve the answer
Let ClickHouse software do safe work, then evaluate the rest with Prometheus-compatible semantics
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 · POST
/api/v1/queryInstant queryGET · POST
/api/v1/query_rangeRange queryGET · POST
/api/v1/seriesSeries discovery