> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ClickHouse 适配器在 dbt OSS、dbt v2 与 dbt platform 中的状态

# dbt OSS、v2 与 Platform（Beta）

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <span>Beta</span>
            </a>;
  }
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#beta-features" className="betaBadge">
            <span>Beta 版功能</span>
        </a>;
};

export const ClickHouseSupportedBadge = () => {
  return <div className="ClickHouseSupportedBadge">
            <div className="ClickHouseSupportedIcon">
                <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                    <path d="M1.30762 1.39073C1.30762 1.3103 1.37465 1.22986 1.46849 1.22986H2.64824C2.72868 1.22986 2.80912 1.29689 2.80912 1.39073V14.4886C2.80912 14.5691 2.74209 14.6495 2.64824 14.6495H1.46849C1.38805 14.6495 1.30762 14.5825 1.30762 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M4.2832 1.39073C4.2832 1.3103 4.35023 1.22986 4.44408 1.22986H5.62383C5.70427 1.22986 5.7847 1.29689 5.7847 1.39073V14.4886C5.7847 14.5691 5.71767 14.6495 5.62383 14.6495H4.44408C4.36364 14.6495 4.2832 14.5825 4.2832 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M7.25977 1.39073C7.25977 1.3103 7.3268 1.22986 7.42064 1.22986H8.60039C8.68083 1.22986 8.76127 1.29689 8.76127 1.39073V14.4886C8.76127 14.5691 8.69423 14.6495 8.60039 14.6495H7.42064C7.3402 14.6495 7.25977 14.5825 7.25977 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M10.2354 1.39073C10.2354 1.3103 10.3024 1.22986 10.3962 1.22986H11.576C11.6564 1.22986 11.7369 1.29689 11.7369 1.39073V14.4886C11.7369 14.5691 11.6698 14.6495 11.576 14.6495H10.3962C10.3158 14.6495 10.2354 14.5825 10.2354 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M13.2256 6.6057C13.2256 6.52526 13.2926 6.44482 13.3865 6.44482H14.5662C14.6466 6.44482 14.7271 6.51186 14.7271 6.6057V9.27354C14.7271 9.35398 14.6601 9.43442 14.5662 9.43442H13.3865C13.306 9.43442 13.2256 9.36739 13.2256 9.27354V6.6057Z" fill="currentColor" />
                </svg>
            </div>
            支持 ClickHouse
        </div>;
};

<ClickHouseSupportedBadge />

<BetaBadge link="https://github.com/ClickHouse/dbt-clickhouse/issues/660" />

dbt 正在基于全新引擎重构，而 ClickHouse 从一开始就参与其中。ClickHouse 现已支持基于 Rust 的新版 dbt 引擎，在 dbt OSS 和 dbt v2 中均可使用；并且首次支持从 dbt 平台连接到 ClickHouse。你的项目无需任何改动：目前在 dbt Core 1.x 上运行的模型、测试和 profile，同样可以在新引擎上运行，不同的只是 binary。

ClickHouse 是 dbt OSS、dbt v2 和 dbt 平台上的首个社区 adapter。dbt 官方的第一方 adapter 与我们同步发布，而我们是 dbt Labs 之外的第一个。dbt Core 1.x 的 Python adapter `dbt-clickhouse` 不会被弃用：我们会持续跟进 dbt 1.x 的 发行版，并同时维护这两个 adapter。

<Warning>
  **尚未可用于 production。** 面向 dbt OSS 和 dbt v2 的 ClickHouse adapter，以及 dbt 平台连接，均尚未正式可用 (GA) 。请仅在开发或暂存项目中使用。
</Warning>

<Note>
  **dbt Core 1.x 的文档同样适用于 dbt OSS 和 dbt v2。** 该 adapter 在两种引擎上的行为一致：其他 dbt 页面中描述的 profiles、模型配置、物化类型和 macros，在 dbt OSS、dbt v2 和 dbt 平台上均可原样使用。例外情况记录在下方的 [v1 与 v2 parity](#parity) 表中。
</Note>

<Note>
  **dbt OSS** 是 v2 引擎的 open-source (Apache 2.0) build。有关它与 dbt v2 和 dbt 平台的关系，请参阅[术语与 availability](#terminology)。
</Note>

实时状态可在 [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660) (v2 与 v1 的 parity，每个领域一个子 issue) 和 [ClickHouse/dbt-clickhouse#555](https://github.com/ClickHouse/dbt-clickhouse/issues/555) (dbt v2) 中查看。

<h4 id="request-access">
  在 dbt 平台中体验 ClickHouse
</h4>

如果你有兴趣参与私有 Beta 测试，请通过 [dbt Labs 的私有 Beta 申请表](https://docs.google.com/forms/d/e/1FAIpQLScjHwRchnKarq_RpNM7hATjphNFxqBEePmAwRtSpMWG1snGHA/viewform) 提交申请。该表单由 dbt Labs 提供，因此你提交的信息将发送给 dbt Labs，而非 ClickHouse。开通后，请参照 dbt 文档中的 [Connect ClickHouse](https://docs.getdbt.com/docs/platform/connect-data-platform/connect-clickhouse) 配置连接。

<h2 id="terminology">
  术语与可用性
</h2>

dbt 有多种形态，同一个 adapter 可以在其中多种形态下运行。下表说明各个名称的含义以及当前的 ClickHouse 支持级别。

| 术语 | 含义 | ClickHouse 状态及获取方式 |
| - | - | - |
| **dbt Core 1.x** | 基于 Python 的 dbt 引擎，open source (Apache 2.0) 。我们的 adapter 是 `dbt-clickhouse`，由 [ClickHouse GitHub 组织](https://github.com/ClickHouse/dbt-clickhouse) 维护，与 `dbt-core` 一并安装。 | **GA，持续维护。** 与 dbt v2 并行持续发布发行版。 |
| **dbt OSS** | 用 Rust 对 dbt 引擎进行的彻底 rewrite，open source (Apache 2.0) 。新版本包含 v1 的全部功能，并带来多项性能提升。 | **Beta。** 请参阅 dbt 文档中的 [dbt v2 升级指南](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v2) 和 [v2 的 ClickHouse 设置页面](https://docs.getdbt.com/docs/local/connect-data-platform/clickhouse-setup?version=2)。ClickHouse adapter 已内置于 dbt binary 中，无需单独安装 package。 |
| **dbt v2** | dbt OSS 加上 dbt Labs 提供的附加功能：SQL 理解、静态分析、LSP、VS Code extension 以及列感知。闭源，依据 [dbt Product Licensing Agreement](https://www.getdbt.com/dbt-fusion-engine-license-agreement) 授权。 | **Beta。** adapter 可与 v2 binary 配合运行，但新的 SQL 功能尚不支持 ClickHouse。 |
| **dbt platform** | 托管版 dbt，原名 dbt Cloud：Studio IDE、定时 jobs、环境、Catalog、Semantic Layer。该平台仅运行 dbt v2，因此平台中的 ClickHouse 即指 v2 adapter。 | **私有 Beta。** 参见[如何申请访问权限](#request-access)。设置方式：参阅 dbt 文档中的 [Connect ClickHouse](https://docs.getdbt.com/docs/platform/connect-data-platform/connect-clickhouse)。 |

<h2 id="beta-status">
  Beta 状态
</h2>

我们使用 `dbt-clickhouse` 的 dbt Core 1.x 集成测试套件来检验 dbt v2 adapter。Beta 意味着核心 dbt 工作流和 ClickHouse Cloud 功能集在已记录的限制范围内均可正常使用；与 v1 的完全对等以及自管理集群支持将在之后提供。

**目前**，该 adapter 通过了完整 v1 套件中超过 81% 的测试，以及适用于 ClickHouse Cloud 的测试中的 92%。所有物化类型均已对等 (`view`、`table`、`incremental`、`materialized_view`、`dictionary`、`snapshot`、`seed`、`ephemeral`) ，并支持完整的表配置集、模型契约、数据测试与单元测试、文档持久化、`clickhouse_s3source()` 以及 dbt Core 1.x 的连接设置。剩余的失败项与下文列出的自管理集群相关工作以及少数引擎侧差异有关。逐项功能对比请参见 [v1 与 v2 对等情况](#parity)。

**后续计划**：面向自管理集群的 `ON CLUSTER` DDL 与分布式物化类型、授权、`dbt clone`、基于表元数据的 `dbt source freshness`，修复剩余缺陷，并通过完整的 v1 测试套件以实现完全对等。以上各项的进展均在 [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660) 中跟踪，每个领域对应一个子 issue。

GA 已列入 roadmap，不久即将推出。准备就绪后我们会更新文档。

<h3 id="out-of-scope">
  Beta 范围之外的内容
</h3>

除下文列出的与 v1 的功能差距之外，还有一些 v2 独有的功能目前不在范围内，但很快就会支持：

* **Semantic Layer / MetricFlow。** 目前尚未添加 ClickHouse 支持。进展跟踪见 [dbt-labs/metricflow#2124](https://github.com/dbt-labs/metricflow/pull/2124)。
* **dbt v2 中的 ClickHouse SQL 智能能力** (dialect 感知的校验、静态分析、LSP、VS Code 扩展中的列感知) 。目前该 adapter 可以配合 dbt v2 二进制文件运行，但尚未包含这些功能。在此之前，ClickHouse 项目的静态分析会被强制设为 `off`，引擎也不会写入列级血缘信息。进展跟踪见 [#736](https://github.com/ClickHouse/dbt-clickhouse/issues/736)。
* **dbt 平台中除用户名和密码之外的其他认证方式。**

<h2 id="parity">
  v1 与 v2 的功能对等情况
</h2>

下表将 `dbt-clickhouse` (v1) 中可用的功能与其在 dbt v2 adapter 中的状态进行对比。除备注另有说明外，所列的每项功能在 v1 中均受支持；状态列对应的是 dbt v2，并同样适用于 dbt OSS。每个待处理项的进展都在 [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660) 中跟踪。

<Badge color="green">已支持</Badge> 目前已可用 · <Badge color="yellow">部分支持</Badge> 在一定限制下可用 · <Badge color="red">尚未支持</Badge> 尚未实现。

### 物化类型

| 特性 | 作用 | dbt v2 | 说明 |
| - | - | - | - |
| `view` | 标准 dbt 视图。 | <Badge color="green">已支持</Badge> | |
| `table` | 支持 engine 与 DDL 选项的全量重建。 | <Badge color="green">已支持</Badge> | |
| `incremental` | 追加或合并新行。 | <Badge color="green">已支持</Badge> | |
| `materialized_view` | 在写入时完成转换的 ClickHouse MV。 | <Badge color="green">已支持</Badge> | |
| `dictionary` | 用于键查找和 join 的 ClickHouse 字典。 | <Badge color="green">已支持</Badge> | |
| `snapshot` | 类型 2 缓慢变化维度。 | <Badge color="green">已支持</Badge> | |
| `seed` | 将 CSV 加载为表。 | <Badge color="green">已支持</Badge> | 数值列类型会被推断为 `Int64`/`Float64`，而非 `Int32`/`Float32`；可使用 `column_types` 显式指定。 |
| `ephemeral` | 内联 CTE，不创建任何对象。 | <Badge color="green">已支持</Badge> | |
| `distributed_table`、`distributed_incremental` | 由 Distributed 引擎承载的分片表。 | <Badge color="red">尚未支持</Badge> | |

### 模型配置

| 特性 | 作用 | dbt v2 | 说明 |
| - | - | - | - |
| 引擎、`ORDER BY`、`PARTITION BY`、`PRIMARY KEY` | 核心 MergeTree DDL 控制项。 | <Badge color="green">已支持</Badge> | |
| 生存时间 (TTL) | 行与列的过期。 | <Badge color="green">已支持</Badge> | |
| 表设置与查询设置 | 按模型在 DDL 和 insert 上指定 `SETTINGS`。 | <Badge color="green">已支持</Badge> | |
| 投影、索引、`sql_header` | 次级结构与前置 SQL。 | <Badge color="green">已支持</Badge> | |
| 模型契约与约束 | 在构建时强制生效的列类型与约束。 | <Badge color="green">已支持</Badge> | |
| 增量模型的 schema 演进 | `on_schema_change` 可新增或同步列。 | <Badge color="green">已支持</Badge> | |
| 列的 `codec` 与 `ttl` | 按列设置压缩与过期。 | <Badge color="green">已支持</Badge> | |

### 测试与文档

| 特性 | 作用 | dbt v2 | 说明 |
| - | - | - | - |
| 数据测试 | 通用测试与单一测试。 | <Badge color="green">已支持</Badge> | |
| 单元测试 | 基于 fixture 输入验证模型逻辑。 | <Badge color="green">已支持</Badge> | |
| 文档持久化 | 将描述写入为 ClickHouse 注释。 | <Badge color="yellow">部分支持</Badge> | 包含 `;` 的描述会失败。 |
| 目录与文档生成 | 供文档站点使用的列元数据。 | <Badge color="green">已支持</Badge> | |
| 列级血缘 | 在 DAG 中追踪列。 | <Badge color="yellow">部分支持</Badge> | v2 中通过 SQL 编译器新增，v1 不支持。只有在 `dbt_project.yml` 中禁用标识符引号时，dbt 平台才会渲染血缘；引擎侧血缘则需要使用 ClickHouse SQL 方言。 |

### 集群与 Cloud

| 特性 | 作用 | dbt v2 | 说明 |
| - | - | - | - |
| ClickHouse Cloud | 推荐的 Beta 配置。 | <Badge color="green">已支持</Badge> | |
| 多副本一致性 | `select_sequential_consistency` 及相关的写后读设置。 | <Badge color="green">已支持</Badge> | |
| `ON CLUSTER` 与 Replicated 引擎 | 在自管理集群上实现 DDL 分发。 | <Badge color="red">尚未支持</Badge> | 支持 ClickHouse Cloud 中的多节点集群。其他依赖 `ON CLUSTER` 传播 DDL 的部署方式尚不支持。对于自管理部署，请仅针对单节点集群进行测试。 |
| `EXCHANGE TABLES` | 重建时的原子交换。 | <Badge color="green">已支持</Badge> | |
| 自定义连接设置 | profile 级别的 `custom_settings`。 | <Badge color="green">已支持</Badge> | |
| ClickHouse 服务器版本 | 最低服务器版本。 | <Badge color="green">已支持</Badge> | 两种引擎均需 25.3+。在 v2 上读取 `UUID` 列需要 26.7+ (较早版本的服务器无法将 `UUID` 转换为 Arrow) 。 |

### 宏与操作

| 功能 | 作用 | dbt v2 | 说明 |
| - | - | - | - |
| S3 表函数宏 | `clickhouse_s3source()` 可在模型中直接读取 S3。 | <Badge color="green">已支持</Badge> | |
| 跨数据库宏 | 例如 `dbt-utils` 中提供的辅助宏。 | <Badge color="green">已支持</Badge> | |
| 授权 | 通过模型配置生成 `GRANT` 语句。 | <Badge color="red">尚未支持</Badge> | |
| `dbt clone` | 在不同环境之间执行 zero-copy 的 `CLONE AS`。 | <Badge color="red">尚未支持</Badge> | |
| 运行结果中的 Query ID | `adapter_response` 中的 `query_id`，用于与 `system.query_log` 关联。 | <Badge color="red">尚未支持</Badge> | |
| `query-comment` | 查询注释配置。 | <Badge color="red">尚未支持</Badge> | 目前尚不支持 `query-comment: null`。 |
| 目录集成 (Iceberg) | 物化到外部目录。 | <Badge color="red">尚未支持</Badge> | v1 中同样不支持；已提供变通方案文档。 |

### 连接与认证

| 特性 | 作用 | dbt v2 | 说明 |
| - | - | - | - |
| Protocol | dbt 与 ClickHouse 通信的方式。 | <Badge color="green">已支持</Badge> | v2 使用 ADBC (基于 HTTP 的 Arrow) ；v1 使用 HTTP 和 native 协议。 |
| 用户名与密码、TLS | 标准认证方式。 | <Badge color="green">已支持</Badge> | |
| mTLS 客户端证书 | `client_cert`、`client_cert_key`、`verify`。 | <Badge color="red">尚未支持</Badge> | 有待 driver 层支持；这些参数可以配置，但会被忽略。 |
| HTTP 客户端选项 | `connect_timeout`、`send_receive_timeout`、`sync_request_timeout`、`compress_block_size`、`server_host_name`。 | <Badge color="red">尚未支持</Badge> | 可以配置，但会被忽略；`server_host_name` 不可用。 |