Skip to content

Update v2 status documentation #780

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
koletzilla merged 4 commits into from
Nov 6, 2026
Merged

Update v2 status documentation #780

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
50de7ea
Update v2 status
koletzilla Nov 5, 2026
87e7143
Small fixes
koletzilla Nov 5, 2026
9c20d5d
Moved "Not planned for v2" to "v1 vs v2 parity"
koletzilla Nov 5, 2026
2d0ef49
Restore "Out of scope for Beta" section
koletzilla Nov 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 43 additions & 31 deletions docs/dbt-core-v2-fusion-and-platform.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,10 @@ ClickHouse is the first community adapter on dbt OSS, dbt v2 and the dbt platfor

<Warning>
**Beta, not yet GA.** The ClickHouse adapter for dbt OSS and dbt v2 is in Beta, and the dbt platform connection is in Private Beta. The dbt Core 1.x adapter, `dbt-clickhouse`, is GA and supported for production use; nothing on this page changes that.

Beta means that every materialization (including `incremental` with all its strategies), model contracts, data and unit tests and the ClickHouse Cloud feature set work today and pass the dbt Core 1.x integration test suite. The features that are still pending are listed in [v1 vs v2 parity](#parity) and that list shrinks with every release. We recommend evaluating dbt v2 in development or staging first, and keeping production on dbt Core 1.x if your project depends on any of the pending features or you need the guarantees of a GA release.

@koletzilla koletzilla Nov 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moved to Details on current status

</Warning>

<Note>
**The dbt Core 1.x documentation also applies to dbt OSS and dbt v2.** The adapter behaves the same way on both engines: the profiles, model configs, materializations and macros described in the other dbt pages work unchanged on dbt OSS, dbt v2 and the dbt platform. The exceptions are documented in the [v1 vs v2 parity](#parity) table below.
**The dbt Core 1.x documentation also applies to dbt OSS and dbt v2.** The new adapter behaves the same way on both engines: the profiles, model configs, materializations and macros described in the other dbt pages work unchanged on dbt OSS, dbt v2 and the dbt platform. The exceptions are documented in the [v1 vs v2 parity](#parity) tables below.
</Note>

<Note>
Expand All @@ -35,7 +33,7 @@ Live status is tracked in [ClickHouse/dbt-clickhouse#660](https://github.com/Cli

#### Try ClickHouse in the dbt platform {#request-access}

If you're interested in testing the private beta, sign up through [dbt Labs' private beta form](https://docs.google.com/forms/d/e/1FAIpQLScjHwRchnKarq_RpNM7hATjphNFxqBEePmAwRtSpMWG1snGHA/viewform). The form belongs to dbt Labs, so the information you submit goes to dbt Labs, not to ClickHouse. Once enabled, follow [Connect ClickHouse](https://docs.getdbt.com/docs/platform/connect-data-platform/connect-clickhouse) in the dbt documentation to set up the connection.
If you're interested in testing the Private Beta, sign up through [dbt Labs' private beta form](https://docs.google.com/forms/d/e/1FAIpQLScjHwRchnKarq_RpNM7hATjphNFxqBEePmAwRtSpMWG1snGHA/viewform). The form belongs to dbt Labs, so the information you submit goes to dbt Labs, not to ClickHouse. Once enabled, follow [Connect ClickHouse](https://docs.getdbt.com/docs/platform/connect-data-platform/connect-clickhouse) in the dbt documentation to set up the connection.

## Terminology and availability {#terminology}

Expand All @@ -48,31 +46,23 @@ dbt is available in several forms, and the same adapter can run in more than one
| **dbt v2** | dbt OSS plus additional features from dbt Labs: SQL comprehension, static analysis, LSP, a VS Code extension and column awareness. Closed source, licensed under the [dbt Product Licensing Agreement](https://www.getdbt.com/dbt-fusion-engine-license-agreement). | **Beta.** The adapter runs with the v2 binary, but the new SQL features are not available for ClickHouse yet. |
| **dbt platform** | Hosted dbt, formerly dbt Cloud: Studio IDE, scheduled jobs, environments, Catalog, Semantic Layer. The platform runs dbt v2 only, so ClickHouse in the platform means the v2 adapter. | **Private Beta.** See [how to request access](#request-access). Setup: [Connect ClickHouse](https://docs.getdbt.com/docs/platform/connect-data-platform/connect-clickhouse) in the dbt documentation. |

## Beta status {#beta-status}
## Details on current status {#v2-adapter-status}

We measure the dbt v2 adapter against the dbt Core 1.x integration test suite of `dbt-clickhouse`. Beta means that core dbt workflows and the ClickHouse Cloud feature set work with documented limits; full v1 parity and self-managed cluster support come after.
Beta means that almost all v1 features work with documented limits. The features that are still pending are listed in [v1 vs v2 parity](#parity) and that list shrinks with every release. We recommend evaluating dbt v2 in development or staging first, and keeping production on dbt Core 1.x if your project depends on any of the pending features or you need the guarantees of a GA release.

**Today,** the adapter passes more than 81% of the full v1 suite and 92% of the tests that apply to ClickHouse Cloud. Every materialization is at parity (`view`, `table`, `incremental`, `materialized_view`, `dictionary`, `snapshot`, `seed`, `ephemeral`), with the full set of table configs, model contracts, data and unit tests, docs persistence, `clickhouse_s3source()` and the dbt Core 1.x connection settings. The remaining failures relate to the self-managed cluster work listed below and a handful of engine-side differences. See [v1 vs v2 parity](#parity) for the feature-by-feature picture.
We measure the dbt v2 adapter against the dbt Core 1.x integration test suite of `dbt-clickhouse`. **Today,** the adapter passes ~98% of the v1 suite (270 of the 276 tests that apply to dbt v2). The remaining failures are engine-side differences, not ClickHouse ones: query comments, `query_id` in run results and the check for a hook configured under both `pre-hook` and `pre_hook`. See [v1 vs v2 parity](#parity) for the feature-by-feature picture.

**Next steps**: `ON CLUSTER` DDL and the distributed materializations for self-managed clusters, grants, `dbt clone`, `dbt source freshness` from table metadata, fixes for the remaining bugs and passing the full v1 test suite to ensure full parity. The progress of all of these is tracked in [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660), with one sub-issue per area.
**Next steps**: query comments, `query_id` in run results, `dbt source freshness` from table metadata, fixes for the remaining bugs and passing the full v1 test suite to ensure full parity. The progress of all of these is tracked in [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660), with one sub-issue per area.

GA is on the roadmap. We are working with dbt Labs on the timeline and will update this page when it's ready.

### Out of scope for Beta {#out-of-scope}

In addition to the v1 parity gaps listed below, a few features exclusive to v2 are outside the current scope but will come soon:

- **Semantic Layer / MetricFlow.** ClickHouse support has not been added yet. Tracked in [dbt-labs/metricflow#2124](https://github.com/dbt-labs/metricflow/pull/2124).
- **ClickHouse SQL intelligence in dbt v2** (dialect-aware validation, static analysis, LSP, column awareness in the VS Code extension). The adapter runs with the dbt v2 binary today but doesn't include these features yet. Until then, static analysis is forced to `off` for ClickHouse projects and the engine writes no column-level lineage. Tracked in [#736](https://github.com/ClickHouse/dbt-clickhouse/issues/736).
- **Additional auth methods** beyond username and password in the dbt platform.

## v1 vs v2 parity {#parity}
### v1 vs v2 parity {#parity}

The tables below compare the features available in `dbt-clickhouse` (v1) with their status in the dbt v2 adapter. Every feature listed is supported in v1 unless the notes say otherwise; the status column is for dbt v2 and applies equally to dbt OSS. The evolution of every pending item is tracked in [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660).

<Badge color="green">Supported</Badge> works today · <Badge color="yellow">Partial</Badge> works with limits · <Badge color="red">Not yet</Badge> pending implementation.

### Materializations {#parity-materializations}
#### Materializations {#parity-materializations}

| Feature | What it does | dbt v2 | Notes |
|---------|--------------|--------|-------|
Expand All @@ -84,9 +74,9 @@ The tables below compare the features available in `dbt-clickhouse` (v1) with th
| `snapshot` | Type 2 slowly changing dimensions. | <Badge color="green">Supported</Badge> | |
| `seed` | Load CSVs as tables. | <Badge color="green">Supported</Badge> | Numeric column types are inferred as `Int64`/`Float64` instead of `Int32`/`Float32`; use `column_types` to set them explicitly. |
| `ephemeral` | Inline CTE, no object created. | <Badge color="green">Supported</Badge> | |
| `distributed_table`, `distributed_incremental` | Sharded tables behind a Distributed engine. | <Badge color="red">Not yet</Badge> | |
| `distributed_table`, `distributed_incremental` | Sharded tables behind a Distributed engine. | <Badge color="green">Supported</Badge> | Self-managed clusters with `cluster` set in the profile, as in v1. |

### Model configuration {#parity-model-configuration}
#### Model configuration {#parity-model-configuration}

| Feature | What it does | dbt v2 | Notes |
|---------|--------------|--------|-------|
Expand All @@ -98,44 +88,66 @@ The tables below compare the features available in `dbt-clickhouse` (v1) with th
| Schema evolution on incremental models | `on_schema_change` adds or syncs columns. | <Badge color="green">Supported</Badge> | |
| Column `codec` and `ttl` | Per-column compression and expiration. | <Badge color="green">Supported</Badge> | |

### Testing and docs {#parity-testing-and-docs}
#### Testing and docs {#parity-testing-and-docs}

| Feature | What it does | dbt v2 | Notes |
|---------|--------------|--------|-------|
| Data tests | Generic and singular tests. | <Badge color="green">Supported</Badge> | |
| Unit tests | Model logic against fixture inputs. | <Badge color="green">Supported</Badge> | |
| Docs persistence | Descriptions written as ClickHouse comments. | <Badge color="yellow">Partial</Badge> | Descriptions containing `;` fail. |
| Docs persistence | Descriptions written as ClickHouse comments. | <Badge color="green">Supported</Badge> | |
| Catalog and docs generation | Column metadata for the docs site. | <Badge color="green">Supported</Badge> | |
| Column-level lineage | Trace columns through the DAG. | <Badge color="yellow">Partial</Badge> | New in v2 via the SQL compiler, not available in v1. dbt platform lineage renders only with identifier quoting disabled in `dbt_project.yml`; engine-side lineage needs the ClickHouse SQL dialect. |

@koletzilla koletzilla Nov 5, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moved to v2 specifics


### Cluster and Cloud {#parity-cluster-and-cloud}
#### Cluster and Cloud {#parity-cluster-and-cloud}

| Feature | What it does | dbt v2 | Notes |
|---------|--------------|--------|-------|
| ClickHouse Cloud | Recommended Beta setup. | <Badge color="green">Supported</Badge> | |
| Multi-replica consistency | `select_sequential_consistency` and related read-after-write settings. | <Badge color="green">Supported</Badge> | |
| `ON CLUSTER` and replicated engines | DDL fan-out on self-managed clusters. | <Badge color="red">Not yet</Badge> | Multi-node clusters in ClickHouse Cloud are supported. Other setups that require `ON CLUSTER` for DDL propagation are not supported yet. For self-managed deployments, test only against single-node clusters. |
| `ON CLUSTER` and replicated engines | DDL fan-out on self-managed clusters. | <Badge color="green">Supported</Badge> | Set `cluster` in the profile. DDL fans out to every node, except on `Replicated` databases where it is not needed; `disable_on_cluster` turns it off per model. |
| `EXCHANGE TABLES` | Atomic swap on rebuild. | <Badge color="green">Supported</Badge> | |
| Custom connection settings | Profile-level `custom_settings`. | <Badge color="green">Supported</Badge> | |
| ClickHouse server version | Minimum server version. | <Badge color="green">Supported</Badge> | 25.3+ on both engines. Reading `UUID` columns on v2 requires 26.7+ (older servers cannot convert `UUID` to Arrow). |

### Macros and operations {#parity-macros-and-operations}
#### Macros and operations {#parity-macros-and-operations}

| Feature | What it does | dbt v2 | Notes |
|---------|--------------|--------|-------|
| S3 table function macro | `clickhouse_s3source()` reads S3 directly in a model. | <Badge color="green">Supported</Badge> | |
| Cross-database macros | Helpers such as those in `dbt-utils`. | <Badge color="green">Supported</Badge> | |
| Grants | `GRANT` statements from model config. | <Badge color="red">Not yet</Badge> | |
| `dbt clone` | Zero-copy `CLONE AS` between environments. | <Badge color="red">Not yet</Badge> | |
| Grants | `GRANT` statements from model config. | <Badge color="green">Supported</Badge> | |
| `dbt clone` | Zero-copy `CLONE AS` between environments. | <Badge color="green">Supported</Badge> | MergeTree tables, seeds, snapshots and incrementals are cloned with `CLONE AS`; views and other engines fall back to views, as in v1. |
| Query ID in run results | `query_id` in `adapter_response` for `system.query_log` correlation. | <Badge color="red">Not yet</Badge> | |
| `query-comment` | Query comment configuration. | <Badge color="red">Not yet</Badge> | `query-comment: null` is not honored yet. |
| Catalog integration (Iceberg) | Materialize into external catalogs. | <Badge color="red">Not yet</Badge> | Not in v1 either; workarounds documented. |

@koletzilla koletzilla Nov 5, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not in v1 anyway, and it's documented in the general docs.


### Connectivity and auth {#parity-connectivity-and-auth}
#### Connectivity and auth {#parity-connectivity-and-auth}

| Feature | What it does | dbt v2 | Notes |
|---------|--------------|--------|-------|
| Protocol | How dbt talks to ClickHouse. | <Badge color="green">Supported</Badge> | ADBC (Arrow over HTTP) on v2; HTTP and native on v1. |
| Username and password, TLS | Standard auth. | <Badge color="green">Supported</Badge> | |
| mTLS client certificates | `client_cert`, `client_cert_key`, `verify`. | <Badge color="red">Not yet</Badge> | Driver work; the keys are accepted but ignored. |
| mTLS client certificates | `client_cert`, `client_cert_key`. | <Badge color="red">Not yet</Badge> | Driver work; the keys are accepted but ignored. |
| HTTP client options | `connect_timeout`, `send_receive_timeout`, `sync_request_timeout`, `compress_block_size`, `server_host_name`. | <Badge color="red">Not yet</Badge> | Accepted but ignored; `server_host_name` is unavailable. |

#### Not planned for v2 {#not-planned}

A few v1 options are deliberately not carried over to v2. They are listed here so the parity tables above only contain work that is planned.

| Feature | What it does in v1 | Why it is not planned |
|---------|--------------------|-----------------------|
| `verify: false` | Skips TLS certificate validation. | It keeps the encryption but drops the authentication, so anyone on the path can impersonate the server and read the credentials. v2 always validates certificates and ignores the key. Use a certificate signed by a CA the client trusts. Open an issue if you need it in v2. |

@koletzilla koletzilla Nov 5, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not really needed right now. I think we should wait for users requesting it.


### dbt v2 specific functionality {#v2-functionality}

dbt v2 adds capabilities that have no equivalent in dbt Core 1.x. They are outside the Beta scope and will come later: most of them build on the engine's understanding of the SQL dialect, which does not exist for ClickHouse yet, but we are working on it. Same legend as above, plus <Badge color="blue">In progress</Badge> for work under way. Tracked in [ClickHouse/dbt-clickhouse#736](https://github.com/ClickHouse/dbt-clickhouse/issues/736).

| Feature | What it does | dbt v2 | Notes |
|---------|--------------|--------|-------|
| ClickHouse SQL dialect in the engine | Dialect-aware SQL parsing that the static features below build on. | <Badge color="red">Not yet</Badge> | Planned. |
| Static analysis | Compile-time SQL validation and type checking without querying the warehouse. | <Badge color="red">Not yet</Badge> | Forced to `off` for ClickHouse projects until the dialect exists. |
| Column-level lineage in the dbt platform | Column lineage view built from the run artifacts. | <Badge color="yellow">Partial</Badge> | Renders only with identifier quoting disabled in `dbt_project.yml`; the platform's fallback parser rejects backtick-quoted names ([dbt-labs/dbt#16646](https://github.com/dbt-labs/dbt/issues/16646)). |
| Column-level lineage from the engine | Lineage written by `dbt docs generate` for the local docs site. | <Badge color="red">Not yet</Badge> | Needs static analysis. |
| LSP and VS Code extension | Dialect-aware autocomplete and column awareness while editing. | <Badge color="red">Not yet</Badge> | Needs the dialect. |
| Source freshness from table metadata | `dbt source freshness` without `loaded_at_field`, from the table's last modification time. | <Badge color="blue">In progress</Badge> | Being implemented. Today the command fails for sources without `loaded_at_field`. |
| Semantic Layer / MetricFlow | Metrics defined in dbt and queried through the Semantic Layer. | <Badge color="red">Not yet</Badge> | ClickHouse support is merged in MetricFlow; we are working with dbt Labs to enable it in the Semantic Layer. |
| Record and replay of adapter calls | `--fs-record` / `--fs-replay` re-run a job without a warehouse. | <Badge color="yellow">Partial</Badge> | ClickHouse catalog details (`ON CLUSTER`, `EXCHANGE`, MV links) are not recorded, so a replay can render different DDL. |
| More authentication methods in the dbt platform | How the platform connects to ClickHouse. | <Badge color="yellow">Partial</Badge> | Username and password only today; more methods are planned. |
Loading