PromQL in HyperDX on a local ClickStack

HyperDX can chart PromQL, but only from a ClickHouse TimeSeries table, and that engine is off by default. This lab turns it on in a local ClickStack container, fills a TimeSeries table from inside ClickHouse (no Prometheus, no collector), registers it as a HyperDX PromQL source, and checks four things with SQL and HTTP: the data, a rate query, a histogram quantile, and the same query through HyperDX's own route.

Why local: the engine's setting cannot be enabled on a ClickHouse Cloud service you do not control the configuration of (issue #117), so Managed ClickStack is not used here.

What it builds

Piece	Where	What
ClickStack all-in-one 2.42.0	docker-compose.yml	the HyperDX version Managed ClickStack runs; bundles ClickHouse 26.8.34.13; ENABLE_PROMQL=true mounts HyperDX's /api/v1/prometheus router, and NEXT_PUBLIC_ENABLE_PROMQL=true gives the chart editor its PromQL mode (without it the UI has only Builder and SQL)
TimeSeries setting	config/timeseries-user.xml	allow_experimental_time_series_table=1 in the default profile (the default, api and worker users use it)
Prometheus HTTP API	config/prometheus.xml	prometheus_api_v1 handler at /prometheus/api/v1 on the ClickHouse HTTP port; no table pinned, HyperDX names it per request
promql.metrics	sql/01-table.sql	ENGINE = TimeSeries, samples inner table with a 1-day TTL
History	sql/02-backfill.sql	3 hours, 15 s apart
Live data	sql/03-refresh.sql	a refreshable MV, every minute, APPEND TO promql.metrics
PromQL source	bin/setup_hyperdx.py	a local test user and a promql source on promql.metrics, through HyperDX's API

Data: four services (cart, checkout, search, payment) and three metrics, 36 series in all: http_requests_total{service,status} (8), http_errors_total{service} (4), and http_request_duration_seconds_bucket{service,le} (24, six buckets each). A counter is rate times elapsed time with a slow swing, computed from the clock, so a refresh needs no state. Each service has a different latency scale, so the p95 differs per service.

Findings that shaped the lab

• Setting name. The bundled server (26.8.34.13) rejects enable_time_series_table in a user profile (UNKNOWN_SETTING, the server does not start) and accepts allow_experimental_time_series_table. The ClickHouse master docs use the first name.
• HTTP API, not the fallback. 26.8 is past 26.6, so HyperDX proxies PromQL to the prometheus_api_v1 handler. The prometheusQuery() table-function fallback is for older servers and is not exercised.
• A refreshable MV can write into a TimeSeries table. CREATE MATERIALIZED VIEW ... REFRESH EVERY 1 MINUTE APPEND TO promql.metrics works, and so does INSERT INTO promql.metrics (metric_name, tags, time_series). The samples column is called time_series on this server (newer schema versions call it samples), and the target takes exactly the columns it has: aliasing the SELECT column samples fails with THERE_IS_NO_COLUMN.
• A TimeSeries table cannot be read with SELECT (NOT_IMPLEMENTED). The checks read it through timeSeriesTags(promql.metrics) and timeSeriesData(promql.metrics). The tags inner table keeps duplicate rows until a merge, so series are counted with uniqExact(id).
• Ports. HyperDX's API listens on 8000 with routes like /v1/prometheus/...; the UI port proxies it under /api/..., so the route in the checks is http://localhost:28080/api/v1/prometheus/query_range.

Run it

Ports are shifted so it can sit beside _base/ (which uses 8080, 8000, 8123); both are heavy, so run one at a time. Change them in .env.

Host port	What	.env
28080	HyperDX UI, and /api/...	PROMQL_UI_PORT
28000	HyperDX API	PROMQL_API_PORT
28123	ClickHouse HTTP and /prometheus/api/v1	PROMQL_CH_HTTP_PORT

cd labs/promql
bin/up.sh            # container, SQL, local test user, PromQL source. Needs docker and python3.
python3 bin/check.py # about 3 minutes: it waits up to 160 s for one refresh

bin/up.sh writes the test user's email and a random password to .env (gitignored, mode 600) and never prints them. Open http://localhost:28080, sign in with them, and add a PromQL tile on the PromQL metrics source. Stop with docker compose down -v.

The checks

	Check	Negative
S1 data	setting on; 8 / 4 / 24 series for the three metrics; sample count grows after a refresh; the MV reports no exception	an unknown metric has no series
S2 PromQL	sum by (service) (rate(http_requests_total[5m])) returns one series per service, through ClickHouse's Prometheus API	a selector matching nothing returns result: []
S3 histogram	histogram_quantile(0.95, sum by (le, service) (rate(http_request_duration_seconds_bucket[5m]))) returns one value per service	a missing metric returns result: []
S4 HyperDX	the source exists; /api/v1/prometheus/query_range returns the same series and values as S2	nothing-matching selector is empty; an unknown sourceId is 404

Verified on ClickStack all-in-one 2.42.0 (HyperDX 2.42.0, as reported by its /health; ClickHouse 26.8.34.13), local, 2026-11-04: bin/up.sh from an empty volume, then bin/check.py 14/14 PASS (negatives included). Fault injection: with the refresh view stopped, S1 refreshable MV adds samples fails; with a wrong test-user password, the S4 login check fails. No OpenTelemetry Collector image is involved in this lab. Re-run 2026-11-05 after adding NEXT_PUBLIC_ENABLE_PROMQL=true (container recreated, volume kept): 14/14 PASS. The UI was checked by hand the same day: the chart editor's PromQL mode charts rate by service, two expressions on one chart, histogram_quantile and a Histogram-mode heatmap from this source. The same flag adds PromQL to the source form's Source Data Type (without it the form offers Logs, Traces, OTel metrics and Sessions only); bin/setup_hyperdx.py creates the source through the API, so the lab does not depend on either.

Retention is a day (TTL on the samples inner table), so the lab stays near 26k samples: 36 series times four new samples per minute after the three-hour backfill.

cd labs/promql
bin/up.sh            # 컨테이너, SQL, 로컬 테스트 사용자, PromQL 소스. docker와 python3 필요
python3 bin/check.py # 약 3분: 리프레시 한 번을 최대 160초 기다림