集成 dbt 与 ClickHouse

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 方法则在此基础上进一步扩展，使后续对底层数据的更新能够反映到目标表中。以下是 dbt-clickhouse 中的实验性功能：

类型	是否支持	详情
Materialized View 物化类型	是。使用显式目标创建处于 Beta 阶段	创建一个 materialized view。
分布式表物化类型	是，Experimental	创建一个分布式表。
分布式增量物化类型	是，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 中，dbt clone 使用零拷贝 CLONE 语句复制 MergeTree 表——详情请参阅下方的使用 dbt clone 克隆模型。我们建议为测试环境 (即暂存环境) 使用专用的 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 clone` 克隆模型

自 dbt-clickhouse 1.10.1 起，dbt clone 命令使用 ClickHouse 的零拷贝 CREATE OR REPLACE TABLE ... CLONE AS ... 语句，克隆物化为采用 MergeTree 家族引擎的表的模型。此操作会创建表副本，但不会复制底层数据分区片段，因此可快速、低成本地同步环境，例如基于生产环境状态搭建开发环境或 Slim CI 环境。无法通过此方式克隆的模型会回退到 dbt 的默认行为：创建一个指向源关系的视图：

使用非 MergeTree 引擎的表
分布式物化类型

对于 materialized view 模型，仅克隆目标表；materialized view 本身会基于克隆后的表创建。

常见问题排查

连接

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

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

了解长时间运行的操作

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

将 dbt 运行与 ClickHouse 查询关联

如需查看服务端详细信息，自 dbt-clickhouse 1.10.1 起，适配器执行的每条语句都会分配一个独立的查询 ID (UUID4) ，并将其传递给 ClickHouse。模型主语句的 ID 会在其 dbt 结果的 adapter_response 中返回，因此可在 run_results.json 等 dbt 制品中获取。您可以在 system.query_log 表中查找该 ID，以查看该语句的耗时和资源使用情况：

SELECT query_id, query, query_duration_ms, read_rows, memory_usage
FROM system.query_log
WHERE query_id = '<query_id from run_results.json>'
  AND type = 'QueryFinish'

请注意，一个物化类型通常会针对每个模型执行多条语句 (DDL、插入等) ，每条语句都有各自的查询 ID；run_results.json 中的查询 ID 仅标识该模型的主语句。若要查找一次运行所涉及的全部语句，请改为根据嵌入在各查询文本中的 dbt 查询注释过滤 system.query_log。查询 ID 还能让使用 dbt 制品的可观测性工具 (例如 Elementary) 自动将 dbt 模型运行与 system.query_log 中的条目关联起来。

限制

当前用于 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 表，然后再在这些表之上创建分布式表。该适配器不管理集群的创建。
当 dbt 在数据库中创建关系 (表/视图) 时，通常会按以下形式创建：{{ database }}.{{ schema }}.{{ table/view id }}。ClickHouse 没有 schema 的概念，因此该适配器使用 {{schema}}.{{ table/view id }}，其中 schema 就是 ClickHouse 数据库。
如果将 ephemeral 模型/CTE 放在 ClickHouse insert 语句的 INSERT INTO 之前，它们将无法工作，参见 https://github.com/ClickHouse/ClickHouse/issues/30323。这一般不会影响大多数模型，但在模型定义和其他 SQL 语句中放置 ephemeral 模型时仍需谨慎。

Fivetran

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

Data sources

Data visualization

Data ingestion

Data integrations

SQL-clients

Tools

dbt-clickhouse 适配器

支持的功能

dbt 概念和支持的物化类型

设置 dbt 和 ClickHouse 适配器

安装 dbt-core 和 dbt-clickhouse

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

创建 dbt 项目

测试连接

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

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

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

使用 `dbt clone` 克隆模型

常见问题排查

连接

了解长时间运行的操作

将 dbt 运行与 ClickHouse 查询关联

限制

Fivetran

​dbt-clickhouse 适配器

​相关页面

​支持的功能

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

​设置 dbt 和 ClickHouse 适配器

​安装 dbt-core 和 dbt-clickhouse

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

​创建 dbt 项目

​测试连接

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

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

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

​使用 dbt clone 克隆模型

​常见问题排查

​连接

​了解长时间运行的操作

​将 dbt 运行与 ClickHouse 查询关联

​限制

​Fivetran

dbt-clickhouse 适配器

相关页面

支持的功能

dbt 概念和支持的物化类型

设置 dbt 和 ClickHouse 适配器

安装 dbt-core 和 dbt-clickhouse

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

创建 dbt 项目

测试连接

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

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

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

使用 `dbt clone` 克隆模型

常见问题排查

连接

了解长时间运行的操作

将 dbt 运行与 ClickHouse 查询关联

限制

Fivetran