ClickHouse TimeSeries Engine Architecture Diagram: PromQL on MergeTree Metrics

On September 15, 2026, ClickHouse introduced a TimeSeries engine path aimed at Prometheus metrics: remote-write in, PromQL (and SQL) out. This ClickHouse TimeSeries engine architecture diagram keeps the preview caveat visible and separates the OTLP path from remote-write.

Ingest path

Collectors and Prometheus agents remote_write into ClickHouse. The TimeSeries engine stores metrics on MergeTree-oriented foundations designed for PromQL-shaped access patterns.

Query surfaces

Operators query via PromQL HTTP, remote-read, client libraries, or SQL functions — including ClickStack PromQL workflows. Draw dual exits: Grafana/PromQL and SQL.

OTLP caveat

OTLP pipelines do not populate TimeSeries tables on this path — remote-write is required. Put that in a red callout so architecture reviews do not invent a dual ingest.

Preview posture

Private preview — cite the ClickHouse introducing-PromQL blog; avoid GA claims. Useful when comparing Prometheus long-term storage options.

Where TimeSeries sits in the metrics stack

Most Prometheus estates eventually outgrow local TSDB retention. Teams evaluate remote write destinations that keep PromQL familiarity while adding durable storage and SQL joins to business data. ClickHouse’s TimeSeries engine preview targets that intersection: keep the Prometheus write path, land series in a MergeTree-oriented engine, and expose PromQL plus SQL. On an architecture diagram, resist collapsing “ClickHouse metrics” into a single cylinder — show the engine as a named component with two query exits and a hard note that private preview features move.

Operational checklist for architecture reviews

When you socialize this pattern, list decisions explicitly: which collectors emit remote_write; which Grafana datasources point at PromQL HTTP versus SQL; how cardinality budgets are enforced before write; and how OTLP pipelines (logs/traces/metrics) remain separate so nobody assumes OTLP silently fills TimeSeries tables. Pair the diagram with a short “not GA” banner. That honesty is part of SEO trust and part of engineering hygiene — preview posts that over-claim become liabilities when GA shapes differ.

Compare alternatives on the same canvas if helpful: Prometheus + object storage, vendor managed Prometheus, or classic ClickHouse tables without the TimeSeries engine. The point of ByteDiagram’s post is not to declare a winner; it is to make the ClickHouse TimeSeries control and data paths drawable so your team can argue with a shared picture.

FAQ

What is the ClickHouse TimeSeries engine?

A Sep 15 2026 private preview table engine path for Prometheus-style metrics on MergeTree foundations, queryable via PromQL surfaces and SQL.

Does OTLP populate TimeSeries tables?

No — for this engine path, Prometheus remote-write is required. Do not assume OTLP fills TimeSeries tables.

How do you query?

PromQL over HTTP/remote-read/clients, plus ClickHouse SQL functions / ClickStack PromQL integration.

Conclusion

Keep the diagram honest to the launch posture: Sep 15 2026 private preview — Prometheus remote-write into TimeSeries; PromQL query surfaces. Sources: ClickHouse blog — Introducing PromQL / TimeSeries (Sep 15 2026 private preview). Browse more architecture diagrams on the ByteDiagram blog.