Skip to content

[FEATURE] ClickHouse: use non-numeric columns of a time series query as series labels - #860

Closed
jonatas-lima wants to merge 1 commit into
perses:mainfrom
jonatas-lima:feat/clickhouse-label-columns
Closed

jonatas-lima wants to merge 1 commit into
perses:mainfrom
jonatas-lima:feat/clickhouse-label-columns

Conversation

@jonatas-lima

Copy link
Copy Markdown

Description

The ClickHouse time series query builds one series per non-time column, named after the column. A text column becomes an all-null series and is filtered out, so there is no way to break a metric down by a dimension:

  • SELECT time, repository, count() AS jobs ... GROUP BY time, repository collapses every repository into a single series named jobs.
  • A Table panel over SELECT repository, coverage shows only the numbers (timestamp NaN); repository is not visible.

Rule

Columns other than time whose non-empty values are all non-numeric text are label columns. Every other column is a value column (current behaviour, including numeric strings and all-null columns). One series is emitted per label combination and value column, with labels set to the label values and name in Prometheus notation, e.g. jobs{repository="network-api"} (labels sorted, as in getUniqueKeyForPrometheusResult). Rows without a time column keep the existing NaN timestamp but carry labels, so the Table panel (which spreads ts.labels into columns) shows one row per label combination.

Backwards compatibility

With no label columns the output is unchanged: same names, same order, no labels field. A test pins this. Queries that previously returned a text column that was silently dropped will now see it as a label, which is the point of the change. The shared stub in the existing test returned an unused service: 'api' column; I removed it so the pre-existing assertions still describe a label-free query.

Tests

Run in clickhouse (Node v24.14.0): npm run test -w clickhouse (17 passed), npm run lint -w clickhouse (no errors, existing warnings only), npm run type-check -w clickhouse, npm run format:check. New tests were written first and failed before the implementation. Not run: Playwright e2e, make targets, and a manual check in a live Perses UI.

Docs: docs/clickhouse/model.md documents label columns.

Screenshots

N/A (no UI change).

Checklist

  • Pull request has a descriptive title and context useful to a reviewer.
  • Pull request title follows the [<catalog_entry>] <commit message> naming convention using one of the following catalog_entry values: FEATURE, ENHANCEMENT, BUGFIX, BREAKINGCHANGE, DOC,IGNORE.
  • All commits have DCO signoffs.

🤖 Generated with Claude Code

…as series labels

Non-numeric columns used to be dropped, so a query grouped by a dimension
collapsed every group into one series. They now become series labels, one
series per label combination and value column. Queries without label
columns return exactly what they returned before.

Signed-off-by: Jonatas Ferreira <62180037+jonatas-lima@users.noreply.github.com>
@jonatas-lima

Copy link
Copy Markdown
Author

Closing as a duplicate of #844, which fixes the same root cause (#843, #841) and was opened first. I'll add a reproduction and before/after screenshots there.

@jonatas-lima
jonatas-lima deleted the feat/clickhouse-label-columns branch October 5, 2026 22:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant