fix(clickhouse): remove _mutate_label workaround and bump clickhouse-connect to >=0.13.0 by joe-clickhouse · Pull Request #38280 · apache/superset

joe-clickhouse · 2026-02-26T22:48:39Z

SUMMARY

Removes the _mutate_label override from ClickHouseConnectEngineSpec that was appending hash suffixes to column aliases as a workaround for column name collision issues in older versions of clickhouse-connect. This is no longer needed as of clickhouse-connect>=0.13.0.

Also bumps the minimum clickhouse-connect version to >=0.13.0 across all locations including pyproject.toml, engine spec metadata, and generated docs for consistency.

BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF

N/A

TESTING INSTRUCTIONS

N/A. This change removes a workaround that is no longer needed with modern versions of clickhouse-connect. The base class _mutate_label already returns the label unchanged, so removing the override is a no-op in terms of behavior.

ADDITIONAL INFORMATION

Has associated issue: Fixes When using clickhouse connect, label mutations do not allow using aliases and virtual columns #33551 which is an artifact of the label mutation
Required feature flags:
Changes UI
Includes DB Migration (follow approval process in SIP-59)
- Migration is atomic, supports rollback & is backwards-compatible
- Confirm DB migration upgrade and downgrade tested
- Runtime estimates and downtime expectations provided
Introduces new feature or API
Removes existing feature or API

bito-code-review · 2026-02-26T22:48:49Z

Code Review Agent Run #8f7c6b

Actionable Suggestions - 0

Review Details

Files reviewed - 2 · Commit Range: e3a18b5..e3a18b5
- pyproject.toml
- superset/db_engine_specs/clickhouse.py
Files skipped - 1
- docs/src/data/databases.json - Reason: Filter setting
Tools
- Whispers (Secret Scanner) - ✔︎ Successful
- Detect-secrets (Secret Scanner) - ✔︎ Successful
- MyPy (Static Code Analysis) - ✔︎ Successful
- Astral Ruff (Static Code Analysis) - ✔︎ Successful

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

/review - Manually triggers a full AI review.
/pause - Pauses automatic reviews on this pull request.
/resume - Resumes automatic reviews.
/resolve - Marks all Bito-posted review comments as resolved.
/abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Superset You can customize the agent settings here or contact your Bito workspace admin at evan@preset.io.

Documentation & Help

AI Code Review powered by

netlify · 2026-02-26T22:50:36Z

✅ Deploy Preview for superset-docs-preview ready!

Name	Link
🔨 Latest commit	`e3a18b5`
🔍 Latest deploy log	https://app.netlify.com/projects/superset-docs-preview/deploys/69a0cdca18c1bd0008de5c62
😎 Deploy Preview	https://deploy-preview-38280--superset-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

villebro

Love this! 🎉

joe-clickhouse · 2026-02-26T23:01:30Z

Hi @rusackas, I chatted offline with @villebro and he advised that the problem can be solved directly in clickhouse-connect and was correct. I have published v0.13.0 which contains the fix that allows the mutation logic to be removed entirely. As a side effect, an entire class of problems like alias interference such as #33551 will be eliminated.

villebro · 2026-02-26T23:02:14Z

@sadpandajoe this is an important fix for ClickHouse users, so if there's a 6.0.1-rc2 forthcoming, please pull this one in!

bito-code-review · 2026-02-27T00:22:55Z

Bito Automatic Review Skipped – PR Already Merged

Bito scheduled an automatic review for this pull request, but the review was skipped because this PR was merged before the review could be run.
No action is needed if you didn't intend to review it. To get a review, you can type /review in a comment and save it

codecov · 2026-02-27T02:11:25Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 64.87%. Comparing base (6589ee4) to head (81b4e03).
⚠️ Report is 2 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #38280      +/-   ##
==========================================
+ Coverage   64.11%   64.87%   +0.76%     
==========================================
  Files        1810     2482     +672     
  Lines       71175   122996   +51821     
  Branches    22650    28515    +5865     
==========================================
+ Hits        45631    79793   +34162     
- Misses      25544    41806   +16262     
- Partials        0     1397    +1397

Flag	Coverage Δ
hive	`41.11% <ø> (?)`
mysql	`64.05% <ø> (?)`
postgres	`64.13% <ø> (?)`
presto	`41.13% <ø> (?)`
python	`65.90% <ø> (?)`
sqlite	`63.72% <ø> (?)`
unit	`100.00% <ø> (?)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

…connect to >=0.13.0 (apache#38280)

ivkhokhlachev · 2026-07-07T15:13:06Z

Looks like this change now brings problems due to a Clickhouse setting prefer_column_name_to_alias
https://clickhouse.com/docs/operations/settings/settings#prefer_column_name_to_alias

Its default value is 0, so "The column name is substituted with the alias."

I'm now testing my charts on Superset 6.1.0 and this removal of random suffixes in column aliases leads to the scenario when applied Time Range filters implicitly depend on a Granularity filter.

E.g. I set values in a Time Range filter: Start 2026-06-10 (which was Wednesday) - End 2026-07-08
Actual Time Range, as shown in a filter, is "2026-06-10 ≤ col < 2026-07-08", days of two months

I select Granularity="Day"
Resulted query:

SELECT toDate("session_start_date_hour") AS "session_start_date_hour"
...
WHERE "session_start_date_hour" >= toDateTime('2026-06-10 00:00:00')
AND "session_start_date_hour" < toDateTime('2026-07-08 00:00:00')

Everything is ok.

I decide to change granularity of the results and select Granularity="Week"
"Actual Time Range" still the same "2026-06-10 ≤ col < 2026-07-08", but the resulted query is:

SELECT dateTrunc('WEEK', toDate("session_start_date_hour")) AS "session_start_date_hour"
...
WHERE "session_start_date_hour" >= toDateTime('2026-06-10 00:00:00')
AND "session_start_date_hour" < toDateTime('2026-07-08 00:00:00')

Due to the prefer_column_name_to_alias=0, the minimal day, included into the results is 2026-06-15, and the whole week before that Monday disappears from the results, while I didn't touch Time Range filter and "Actual Time Range" still says me it should be there.

And the same for Granularity="Month"
Resulted query:

SELECT dateTrunc('MONTH', toDate("session_start_date_hour")) AS "session_start_date_hour"
...
WHERE "session_start_date_hour" >= toDateTime('2026-06-10 00:00:00')
AND "session_start_date_hour" < toDateTime('2026-07-08 00:00:00')

So only results for July are shown.

In Superset 4.1.2, which we have on prod now, there's no such issue, cause the resulted query is always like

SELECT dateTrunc('MONTH', toDate("session_start_date_hour")) AS "session_start_date_hour_a6264a"
...
WHERE "session_start_date_hour" >= toDateTime('2026-06-10 00:00:00')
AND "session_start_date_hour" < toDateTime('2026-07-08 00:00:00')

so dynamic column aliases do not affect filters.

Did I miss anything about this update?

joe-clickhouse · 2026-07-24T20:56:22Z

Hi @ivkhokhlachev did you try setting prefer_column_name_alias=1? You can set it in the engine params as:

{"connect_args": {"settings": {"prefer_column_name_to_alias": 1}}}

I ran an test locally and I think that'll solve the issue. It's probably worth a followup PR to default that value to 1 in the engine spec.

villebro · 2026-07-24T21:21:18Z

Hi @ivkhokhlachev , thanks for the detailed write-up. I agree with @joe-clickhouse that setting it by default to 1 is the correct way to address this, as Superset heavily depends on this assumption. I think the best solution would be to default connect_args to {"settings": {"prefer_column_name_to_alias": 1}}, and then merge any additional connect_args the user defines into the final dict (some type of deep merge that would allow adding new settings but retaining the default seems best).

@ivkhokhlachev

Applies the pre-apache#38280 6-char hash suffix to column aliases on both ``ClickHouseEngineSpec`` (clickhouse-sqlalchemy) and ``ClickHouseConnectEngineSpec`` by placing the ``_mutate_label`` override on the shared ``ClickHouseBaseEngineSpec``. Fixes ClickHouse 25.3+ raising ``Code: 215`` on charts against virtual datasets when the outer alias collides lexically with a subquery column name. Also addresses @ivkhokhlachev's related regression on the apache#38280 thread where time-range filters silently narrow when the granularity changes (same root cause: alias == subquery column name → ClickHouse's ``prefer_column_name_to_alias=0`` substitutes the aliased expression into the WHERE clause). Documented in UPDATING.md: cached results keyed on the old aliases will miss the cache once on upgrade, exported CSV/XLSX column names for ClickHouse charts include the suffix, and any downstream consumer that parses column headers will see the new names. Fixes apache#40289

@ivkhokhlachev

Applies the pre-apache#38280 6-char hash suffix to column aliases on both ``ClickHouseEngineSpec`` (clickhouse-sqlalchemy) and ``ClickHouseConnectEngineSpec`` by placing the ``_mutate_label`` override on the shared ``ClickHouseBaseEngineSpec``. Fixes ClickHouse 25.3+ raising ``Code: 215`` on charts against virtual datasets when the outer alias collides lexically with a subquery column name. Also addresses @ivkhokhlachev's related regression on the apache#38280 thread where time-range filters silently narrow when the granularity changes (same root cause: alias == subquery column name → ClickHouse's ``prefer_column_name_to_alias=0`` substitutes the aliased expression into the WHERE clause). Documented in UPDATING.md: cached results keyed on the old aliases will miss the cache once on upgrade, exported CSV/XLSX column names for ClickHouse charts include the suffix, and any downstream consumer that parses column headers will see the new names. Fixes apache#40289

remove ch label mutation logic

e3a18b5

pull-request-size Bot added the size/M label Feb 26, 2026

github-actions Bot added the doc Namespace | Anything related to documentation label Feb 26, 2026

dosubot Bot added the data:connect:clickhouse Related to Clickhouse label Feb 26, 2026

villebro approved these changes Feb 26, 2026

View reviewed changes

joe-clickhouse added 2 commits February 26, 2026 15:19

remove mutation-specific tests, add note to updating

6673a1b

linting

81b4e03

villebro merged commit bb6ee9e into apache:master Feb 27, 2026
64 checks passed

qfcwell pushed a commit to qfcwell/superset that referenced this pull request May 12, 2026

fix(clickhouse): remove _mutate_label workaround and bump clickhouse-…

89b4a98

…connect to >=0.13.0 (apache#38280)

dosubot Bot mentioned this pull request May 20, 2026

ClickHouse Error 215: Column not in GROUP BY when using virtual tables in charts (Superset 6.1.0 + ClickHouse 25.3.1.2703) #40289

Closed

3 tasks

Abdulrehman-PIAIC80387 mentioned this pull request Aug 5, 2026

fix(clickhouse): restore label hash suffix to avoid Code 215 on virtual datasets #42793

Closed

6 tasks

Navigation Menu

Uh oh!

fix(clickhouse): remove _mutate_label workaround and bump clickhouse-connect to >=0.13.0 - #38280

fix(clickhouse): remove _mutate_label workaround and bump clickhouse-connect to >=0.13.0#38280
villebro merged 3 commits into
apache:masterfrom
joe-clickhouse:joe/remove-ch-mutation-logic

joe-clickhouse commented Feb 26, 2026

Uh oh!

bito-code-review Bot commented Feb 26, 2026 •

edited

Loading

Code Review Agent Run #8f7c6b

Uh oh!

netlify Bot commented Feb 26, 2026

Uh oh!

villebro left a comment

Uh oh!

joe-clickhouse commented Feb 26, 2026

Uh oh!

villebro commented Feb 26, 2026 •

edited

Loading

Uh oh!

Uh oh!

bito-code-review Bot commented Feb 27, 2026

Uh oh!

codecov Bot commented Feb 27, 2026 •

edited

Loading

Uh oh!

ivkhokhlachev commented Jul 7, 2026

Uh oh!

joe-clickhouse commented Jul 24, 2026

Uh oh!

villebro commented Jul 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

joe-clickhouse commented Feb 26, 2026

SUMMARY

BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF

TESTING INSTRUCTIONS

ADDITIONAL INFORMATION

Uh oh!

bito-code-review Bot commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review Agent Run #8f7c6b

Uh oh!

netlify Bot commented Feb 26, 2026

✅ Deploy Preview for superset-docs-preview ready!

Uh oh!

villebro left a comment

Choose a reason for hiding this comment

Uh oh!

joe-clickhouse commented Feb 26, 2026

Uh oh!

villebro commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

bito-code-review Bot commented Feb 27, 2026

Uh oh!

codecov Bot commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ivkhokhlachev commented Jul 7, 2026

Uh oh!

joe-clickhouse commented Jul 24, 2026

Uh oh!

villebro commented Jul 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bito-code-review Bot commented Feb 26, 2026 •

edited

Loading

villebro commented Feb 26, 2026 •

edited

Loading

codecov Bot commented Feb 27, 2026 •

edited

Loading