TimeSeries Engine + PromQL — Self-managed ClickHouse

---

A hands-on lab for ClickHouse's TimeSeries table engine and its PromQL query dialect — both still experimental, both changing release to release, and both barely documented beyond "here is the flag name". This lab was built by actually running every statement against a real container and recording what happened, including the parts the docs get wrong or leave out.

Verified against ClickHouse 26.8.8 — every script in this directory runs end to end with zero exceptions.

Why these two features, together

The TimeSeries engine gives ClickHouse a native way to store Prometheus-shaped data (a metric name, a set of tags, and a series of timestamped samples). PromQL is the query language that data is shaped for — plain SQL can read the same rows, but PromQL's rate(), by (...), and range-vector selectors are what make "what was the error rate per host over the last hour" a one-liner instead of a window-function exercise. Neither one is very useful to learn in isolation.

Feature history (so you know what to expect on other versions)

Version	What landed
24.8 LTS (2024-08-30)	TimeSeries table engine introduced, behind allow_experimental_time_series_table (PR #64183, merged 2024-08-08)
25.6 (2025-06-26)	timeSeries*ToGrid SQL-native helper/aggregate functions added — a separate, later addition, not the engine itself (PR #80590, merged 2025-06-05)
25.8 (2025-08-28)	PromQL dialect introduced (SET dialect = 'promql'), basic rate/delta/increase (PR #75036, merged 2025-08-23)
25.9 → 26.8	Ongoing work: more PromQL functions and operators, topk/bottomk, direct SQL SELECT on a TimeSeries table still not implemented as of 26.8
26.9+ (unreleased at time of writing)	SELECT support for TimeSeries tables, max_over_time/min_over_time, Prometheus HTTP API endpoints — still evolving; treat every detail in this README as version-specific, not a stable contract

Both features require ClickHouse 25.8 or later to use together at all; this lab targets 26.8 LTS because that is what has the richest, best-tested feature set today, and because it is the version already used by local/releases/26.8 in this repository.

What you will find in each file

File	What it covers
00-setup.sh	Pins ClickHouse 26.8 via local/oss-docker
01-schema.sql	CREATE TABLE ... ENGINE = TimeSeries; what it actually builds under the hood (4 inner tables)
02-load.sql	Loads 6 synthetic series (3 hosts × 2 metrics), 240 samples each
03-promql-instant.sql	Instant vectors, label matching, by (...) aggregation, topk
04-promql-range.sql	rate/delta semantics, operators, and range queries — the shape a dashboard graph actually needs
05-management.sql	Two gotchas that will otherwise cost you a debugging session, inspecting the inner tables directly, cleanup
REFERENCE.md	Standalone cheat sheet: settings, schema, insert format, verified PromQL syntax, gotchas — no need to run anything

Gotchas (the reason this lab exists)

1. There is a second, similarly-named setting — allow_experimental_time_series_aggregate_functions — and whether you need it is inconsistent. It clearly gates the SQL-native timeSeries*ToGrid aggregate function family from 25.6 (timeSeriesRateToGrid, timeSeriesResampleToGridWithStaleness, etc.), which prometheusQueryRange() uses internally. In this lab's own testing, prometheusQueryRange() failed with UNKNOWN_AGGREGATE_FUNCTION without it on one run, then succeeded without it on a freshly restarted container moments later — same version, same query. Plain PromQL keyword functions (rate(), topk() via SET dialect = 'promql') worked in every test regardless of this setting. Until that inconsistency is understood, set it defensively alongside allow_experimental_time_series_table — it never hurts, and it has been observed to matter for range queries.
2. SELECT * FROM <timeseries_table> does not work, even after you have created the table and inserted data (Code: 48, NOT_IMPLEMENTED). Read it back through PromQL, or through the four inner tables directly.
3. The dialect setting is session-wide. SET dialect = 'promql' turns every subsequent statement into PromQL text until you switch it back — including things you might expect to still be SQL, like a SELECT '...' banner between two PromQL queries (it will fail to parse as PromQL).
4. rate() fails silently, not loudly, if a window (like [2m]) does not contain at least two samples — no error, just an empty result.

Prerequisites

• Docker (for local/oss-docker)
• Nothing else — the lab installs and pins its own ClickHouse version

Running the lab

cd usecase/timeseries-promql-oss
./00-setup.sh
./01-schema.sh
./02-load.sh
./03-promql-instant.sh
./04-promql-range.sh
./05-management.sh   # ends by dropping the table

On ClickHouse Cloud

There is no Cloud counterpart to this lab, and that is a statement about the feature rather than about the lab. As of this writing the TimeSeries engine is Private Preview only on ClickHouse Cloud: most Cloud services cannot self-enable it, and PromQL depends on a TimeSeries table existing, so the whole feature pair sits behind the same private-preview approval. Run this lab against OSS until that changes.

What differs on a preview service. Cloud does not reimplement either feature. It runs the same engine and the same PromQL code. What differs is what surrounds them. Sources: the TimeSeries engine and Prometheus protocols docs, read 2026-10-01. None of this has been run on a Cloud service.

• Enabling. On preview services, ClickHouse has already set the setting and configured the Prometheus HTTP endpoints; no other service can turn them on. In OSS you set the setting yourself and register a prometheus_api_v1 handler under <http_handlers> in config.xml. This lab uses neither endpoint: it writes with SQL INSERT and reads with SET dialect = 'promql'.
• The setting's name. The docs call it enable_time_series_table. That name does not exist in 26.8: on 26.8.15.10, system.settings has only allow_experimental_time_series_table, the name this lab uses. On 26.9.1.1629 enable_time_series_table is the setting and the old name is its alias, so the lab's name works on both.
• Storage under the engine. The four inner tables follow default_table_engine, and the docs require them all to share one replication type (all replicated or all shared). On Cloud they should therefore be Shared* engines, and merge and deduplication timing may not match what this lab sees on a single node. This is a hypothesis, not a measurement.
• Version. A Cloud service runs its own version, not this lab's 26.8 pin. 26.9 added SELECT on TimeSeries tables (see local/releases/26.9), so gotcha 2 above may not reproduce there.

To see the second and third points on a preview service, run SELECT version() after 01-schema.sql. Then run the inner-table query in 05-management.sql without its DROP, adding engine to the columns.

---

cd usecase/timeseries-promql-oss
./00-setup.sh
./01-schema.sh
./02-load.sh
./03-promql-instant.sh
./04-promql-range.sh
./05-management.sh   # 마지막에 테이블을 삭제합니다