集成 dbt 与 ClickHouse - ClickHouse Documentation

dbt-clickhouse 适配器

dbt (data build tool) 让分析工程师只需编写 SELECT 语句，即可在其数据仓库中转换数据。dbt 会将这些 SELECT 语句物化为数据库中的表和视图等对象，也就是完成 Extract Load and Transform (ELT) 中的 T。你可以创建由 SELECT 语句定义的模型。在 dbt 中，这些模型可以相互引用并分层组织，从而构建更高层级的概念。连接各模型所需的样板 SQL 会自动生成。此外，dbt 还能识别模型之间的依赖关系，并通过有向无环图 (DAG) 确保按正确的顺序创建它们。 dbt 可通过 ClickHouse 支持的适配器与 ClickHouse 兼容。

页面	描述
功能与配置	可用功能和通用配置的说明
物化类型	可用的物化类型及其配置
Materialized views	materialized_view 物化类型的专门文档
指南	使用 dbt 和 ClickHouse 的指南

支持的功能

支持的功能列表：支持截至 dbt-core 1.10 的所有功能，包括 --sample 标志，并且已修复所有面向后续版本的弃用警告。dbt 1.10 中引入的Catalog 集成 (例如 Iceberg) 目前尚未在该适配器中获得原生支持，但已有可用的变通方案。详情请参见 Catalog Support 部分。该适配器暂时还无法在 dbt Cloud 中使用，但我们预计很快会提供支持。如需了解更多信息，请联系支持团队。

dbt 概念和支持的物化类型

dbt 引入了“模型”这一概念。模型被定义为一条 SQL 语句，可能会连接多个表。一个模型可以通过多种方式进行“物化”。物化类型表示模型的 select 查询采用何种构建策略。物化类型背后的代码是样板 SQL，会将你的 SELECT 查询封装进一条语句中，以创建新的关系或更新现有关系。 dbt 提供 5 种物化类型，dbt-clickhouse 全部支持：

view (默认) ：模型会在数据库中构建为视图。在 ClickHouse 中，这会构建为一个视图。
table：模型会在数据库中构建为表。在 ClickHouse 中，这会构建为一个表。
ephemeral：模型不会直接在数据库中构建，而是会作为 CTE (Common Table Expressions，公用表表达式) 被引入依赖它的模型中。
incremental：模型最初会被物化为表，在后续运行中，dbt 会向表中插入新行并更新发生变化的行。
materialized view：模型会在数据库中构建为 materialized view。在 ClickHouse 中，这会构建为一个materialized view。

附加的语法和子句定义了当这些模型的底层数据发生变化时应如何更新。dbt 通常建议先从 view 物化类型开始，直到性能成为关注重点。table 物化类型通过将模型查询结果保存为表来提升查询时性能，但代价是会增加存储开销。incremental 方法则在此基础上进一步扩展，使后续对底层数据的更新能够反映到目标表中。 ClickHouse 的当前适配器还支持 dictionary、distributed table 和 distributed incremental 物化类型。该适配器还支持 dbt 的 snapshots 和 seeds。以下是 dbt-clickhouse 中的实验性功能：

类型	是否支持	详情
Materialized View 物化类型	是。使用显式目标创建处于 Beta 阶段	创建一个 materialized view。
分布式表物化类型	是，Experimental	创建一个分布式表。
Distributed incremental 物化类型	是，Experimental	这是一种基于与分布式表相同思路的增量模型。请注意，并非所有策略都受支持，更多信息请参阅相关文档章节。
字典物化类型	是，Experimental	创建一个字典。

设置 dbt 和 ClickHouse 适配器

安装 dbt-core 和 dbt-clickhouse

dbt 提供了多种安装命令行界面 (CLI) 的方式，详细说明请参见此处。我们建议使用 pip 安装 dbt 和 dbt-clickhouse。

pip install dbt-core dbt-clickhouse

为 dbt 提供 ClickHouse 实例的连接信息。

在 ~/.dbt/profiles.yml 文件中配置 clickhouse-service profile，并提供 schema、主机、端口、用户名和密码等属性。完整的连接配置选项列表可参见功能与配置页面：

clickhouse-service:
  target: dev
  outputs:
    dev:
      type: clickhouse
      schema: [ default ] # 用于 dbt 模型的 ClickHouse 数据库

      # 可选
      host: [ localhost ]
      port: [ 8123 ]  # 默认值为 8123、8443、9000 或 9440，具体取决于 secure 和 driver 设置 
      user: [ default ] # 用于所有数据库操作的用户
      password: [ <empty string> ] # 该用户的密码
      secure: True  # 使用 TLS（native protocol）或 HTTPS（HTTP protocol）

创建 dbt 项目

现在，您可以在现有项目中使用此 profile，或使用以下命令新建一个项目：

dbt init project_name

在 project_name 目录中，更新 dbt_project.yml 文件，指定用于连接 ClickHouse server 的 profile 名称。

profile: 'clickhouse-service'

测试连接

使用 CLI 工具执行 dbt debug，确认 dbt 能否连接到 ClickHouse。确认返回结果中包含 Connection test: [OK connection ok]，表示连接成功。前往指南页面，了解如何将 dbt 与 ClickHouse 配合使用的更多信息。

测试和部署你的模型 (CI/CD)

测试和部署 dbt 项目的方法有很多。对于最佳实践工作流和 CI 作业，dbt 也提供了一些建议。下面我们会介绍几种策略，但请注意，这些策略可能需要根据你的具体使用场景进行较大调整。

使用简单数据测试和单元测试的 CI/CD

快速启动 CI 管道的一种简单方法，是在你的 job 中运行一个 ClickHouse 集群，然后针对该集群运行你的模型。你可以在运行模型之前，先向该集群插入演示数据。你只需使用一个 seed，即可用生产数据的一个子集填充暂存环境。数据插入完成后，你就可以运行数据测试和单元测试。你的 CD 步骤也可以很简单：直接针对生产环境中的 ClickHouse 集群运行 dbt build。

更完整的 CI/CD 阶段：使用最新数据，只测试受影响的模型

一种常见策略是使用 Slim CI 作业，只重新部署被修改的模型 (以及它们的上下游依赖) 。这种方法利用生产运行生成的制品 (即 dbt manifest) ，以缩短项目运行时间，并确保各环境之间不会出现 schema 漂移。为了让开发环境保持同步，并避免让模型针对过时的部署运行，你可以使用 clone，甚至 defer。我们建议为测试环境 (即暂存环境) 使用专用的 ClickHouse 集群或服务，以避免影响生产环境的运行。为了确保测试环境具有代表性，务必要使用生产数据的一个子集，并以能够防止环境之间出现 schema 漂移的方式运行 dbt。

如果你不需要使用最新数据进行测试，可以将生产数据的备份恢复到暂存环境中。
如果你需要使用最新数据进行测试，可以结合使用 remoteSecure() table function 和可刷新materialized view，按所需频率执行 insert。另一种做法是将对象存储作为中间层，定期从生产服务写入数据，再通过对象存储 table function 或 ClickPipes (用于持续摄取) 将其导入暂存环境。

使用专用环境进行 CI 测试，也便于你在不影响生产环境的情况下执行手动测试。例如，你可能希望将某个 BI 工具指向该环境进行测试。对于部署 (即 CD 步骤) ，我们建议使用生产部署生成的制品，只更新发生变化的模型。这需要将对象存储 (例如 S3) 配置为 dbt 制品的中间存储。完成设置后，你可以运行类似 dbt build --select state:modified+ --state path/to/last/deploy/state.json 的命令，根据自上次生产运行以来的变更，有选择地仅重建所需的最少模型。

常见问题排查

连接

如果你在使用 dbt 连接 ClickHouse 时遇到问题，请确保满足以下条件：

所用引擎必须是受支持的引擎之一。
你必须具备访问数据库的足够权限。
如果你使用的不是数据库的默认表引擎，则必须在模型配置中指定表引擎。

了解长时间运行的操作

由于某些特定的 ClickHouse 查询，部分操作的耗时可能会超出预期。为了更清楚地了解哪些查询耗时较长，请将日志级别提升到 debug——这样会输出每个查询的耗时。例如，可以通过在 dbt 命令中附加 --log-level debug 来实现。

限制

当前用于 dbt 的 ClickHouse 适配器有一些限制需要注意：

该插件使用的语法要求 ClickHouse 版本为 25.3 或更高。我们不测试较旧版本的 ClickHouse，目前也不测试 Replicated 表。
如果同时运行，不同的 dbt-adapter 运行之间可能会发生冲突，因为它们在内部可能会为相同操作使用相同的表名。更多信息，请参见问题 #420。
该适配器当前使用 INSERT INTO SELECT 将模型 materialize 为表。这实际上意味着如果再次执行运行，会产生重复数据。超大数据集 (PB 级) 可能会导致运行时间极长，从而使某些模型不具备可行性。要提升性能，请通过将视图实现为 materialized: materialization_view 来使用 ClickHouse Materialized Views。此外，应尽可能使用 GROUP BY，以减少任何查询返回的行数。相比只做转换但保持 source 行数不变的模型，应优先选择对数据进行汇总的模型。
要使用分布式表来表示模型，必须先在每个节点上手动创建底层 replicated 表，然后再在这些表之上创建 Distributed 表。该适配器不管理 cluster 的创建。
当 dbt 在 database 中创建 relation (表/视图) 时，通常会按以下形式创建：{{ database }}.{{ schema }}.{{ table/view id }}。ClickHouse 没有 schema 的概念，因此该适配器使用 {{schema}}.{{ table/view id }}，其中 schema 就是 ClickHouse database。
如果将 ephemeral 模型/CTE 放在 ClickHouse insert 语句的 INSERT INTO 之前，它们将无法工作，参见 https://github.com/ClickHouse/ClickHouse/issues/30323。这一般不会影响大多数模型，但在模型定义和其他 SQL 语句中放置 ephemeral 模型时仍需谨慎。

Fivetran

dbt-clickhouse 连接器也可用于 Fivetran transformations，从而能够在 Fivetran 平台内直接使用 dbt 实现无缝集成和转换。

​dbt-clickhouse 适配器

​相关页面

​支持的功能

​dbt 概念和支持的物化类型

​设置 dbt 和 ClickHouse 适配器

​安装 dbt-core 和 dbt-clickhouse

​为 dbt 提供 ClickHouse 实例的连接信息。

​创建 dbt 项目

​测试连接

​测试和部署你的模型 (CI/CD)

​使用简单数据测试和单元测试的 CI/CD

​更完整的 CI/CD 阶段：使用最新数据，只测试受影响的模型

​常见问题排查

​连接

​了解长时间运行的操作

​限制

​Fivetran