通用物化类型配置
下表列出了一些可用物化类型共用的配置。有关通用 dbt 模型配置的详细信息,请参阅 dbt 文档:支持的表引擎
注意:对于 materialized view,所有 *MergeTree 引擎均受支持。
Experimental 支持的表引擎
如果你在使用上述任一引擎时遇到 dbt 连接 ClickHouse 的问题,请在这里提交
issue。
关于模型设置的说明
ClickHouse 有多种类型/层级的“设置”。在上面的模型配置中,其中有两类是可配置的。settings 指的是在 CREATE TABLE/VIEW 这类 DDL 语句中使用的 SETTINGS
子句,因此通常是特定于具体 ClickHouse 表引擎的设置。新增的
query_settings 用于为模型物化所使用的 INSERT 和 DELETE 查询添加 SETTINGS 子句 (
包括增量物化类型) 。
ClickHouse 有数百种设置,而且“表”设置和“用户”
设置的界限并不总是那么清晰 (不过后者通常
可在 system.settings 表中找到) 。一般来说,建议使用默认值;如需使用这些属性,
应先经过充分研究和测试。
列配置
注意: 以下列配置选项要求强制执行 模型契约。
schema 配置示例
添加复杂类型
dbt 会通过分析用于创建模型的 SQL,自动确定每一列的数据类型。不过,在某些情况下,这一过程可能无法准确判断数据类型,导致与 契约data_type 属性中指定的类型发生冲突。为了解决这个问题,我们建议在模型 SQL 中使用 CAST() 函数来显式指定所需的类型。例如:
物化:视图
dbt 模型可创建为 ClickHouse 视图, 并可使用以下语法进行配置: 项目文件 (dbt_project.yml) :
models/<model_name>.sql) :
物化:表
可将 dbt 模型创建为 ClickHouse 表,并使用以下语法进行配置: 项目文件 (dbt_project.yml) :
models/<model_name>.sql) :
数据跳过索引
你可以通过indexes 配置,为 table 物化类型添加数据跳过索引:
投影
你可以使用projections 配置,为 table 和 distributed_table 物化类型添加投影。每个投影条目都需要 query 或 index 键之一 (不能同时使用两者) 。
注意:对于分布式表,投影会应用到 _local 表上,而不是分布式代理表本身。
注意:在同一个投影条目上同时指定 query 和 index 会引发编译时错误。
查询投影
使用query 定义完整的投影查询:
索引投影
使用index 作为轻量级索引投影的语法糖。此类投影使用 _part_offset 虚拟列。传入单个列名或列名列表作为排序依据:
物化:incremental
每次执行 dbt 时,表模型都会被重建。对于较大的结果集或复杂的转换,这样做可能并不现实,而且成本很高。为应对这一问题并缩短构建时间,可以将 dbt 模型创建为增量式 ClickHouse 表,并使用以下语法进行配置:dbt_project.yml 中的模型定义:
models/<model_name>.sql 的配置块中:
配置
下面列出了此物化类型特有的配置:增量模型策略
dbt-clickhouse 支持以下增量模型策略。
默认 (旧版) 策略
一直以来,ClickHouse 对更新和删除的支持都比较有限,主要通过异步“变更”实现。 为了模拟预期中的 dbt 行为, dbt-clickhouse 默认会创建一个新的临时表,其中包含所有未受影响 (未删除、未更改) 的“旧” 记录,以及所有新增或更新后的记录, 然后将这个临时表与现有增量模型的 relation 交换。这是唯一一种 在操作完成前如果出现问题时仍能保留原始 relation 的策略;不过,由于它需要完整复制原始表,因此执行起来可能 成本较高且速度较慢。Delete+Insert 策略
delete+insert 策略使用轻量级删除移除受影响的行,然后插入新行。由于无需复制整个表,其性能显著优于“legacy”策略。在 profile 中设置 use_lw_deletes: true 会将 delete+insert 设为默认的增量策略。
使用此策略时需注意以下事项:
- 它直接在受影响的表上操作,不会创建任何中间表或临时表,因此如果操作过程中出现 问题,增量模型中的数据很可能处于无效状态。
- 它需要启用 ClickHouse 设置
allow_nondeterministic_mutations。adapter 会尽可能在其 自身 session 中自动启用该设置。如果无法启用 (例如,您的 dbt 用户对此设置只有只读权限) ,具体行为 取决于策略的选择方式:使用默认策略的模型会静默回退到 legacy 策略;显式设置delete+insert或microbatch的模型会在运行时失败;而 profile 中的use_lw_deletes: true会在连接时失败。 - 在极少数情况下,使用非确定性的
incremental_predicates可能会导致已 更新或删除的项发生竞态条件。为确保结果一致,增量谓词应仅包含针对增量物化期间不会被修改的数据的子查询。
微批次策略 (需要 dbt-core >= 1.9)
增量策略microbatch 是 dbt-core 自 1.9 版本起提供的一项功能,旨在高效处理大规模时间序列数据转换。在 dbt-clickhouse 中,它基于现有的 delete_insert
增量策略,根据 event_time 和
batch_size 模型配置,将增量处理拆分为预定义的时间序列批次。
除了能够处理大规模转换,微批次还支持:
有关微批次的详细用法,请参阅官方文档。
追加策略
该策略取代了早期版本 dbt-clickhouse 中的inserts_only 设置。这种方式只是将
新行追加到现有 relation 中。
因此,重复行不会被去除,也不会使用临时表或中间表。如果数据允许重复,
或者增量查询的 WHERE 子句/过滤器已将重复项排除在外,那么这是最快的
方式。
insert_overwrite 策略 (Experimental)
[IMPORTANT]
当前,insert_overwrite 策略尚未完全支持分布式物化类型。
执行以下步骤:
- 创建一个与增量模型 relation 结构相同的暂存 (临时) 表:
CREATE TABLE <staging> AS <target>. - 仅将新记录 (由
SELECT生成) 插入到暂存表中。 - 仅将新分区 (即暂存表中存在的分区) 替换到目标表中。
- 它比默认策略更快,因为不需要复制整个表。
- 它比其他策略更安全,因为在 INSERT 操作成功完成之前,不会修改原始表: 如果中途失败,原始表不会被修改。
- 它实现了“分区不可变性”这一数据工程最佳实践,从而简化增量和并行数据 处理、回滚等操作。
partition_by。模型配置中所有其他特定于策略的
参数都会被忽略。
物化:materialized_view
materialized_view 物化会创建一个 ClickHouse materialized view,它可充当插入触发器,自动将源表中的新行转换后插入到目标表中。这是 dbt-clickhouse 中最强大的物化类型之一。
由于这一物化较为复杂,我们为其提供了单独的页面。完整文档请参阅 Materialized Views 指南
物化:字典 (Experimental)
dbt 模型可以创建为 ClickHouse 字典。每次执行dbt run 时,都会使用 CREATE OR REPLACE DICTIONARY 将字典替换为当前的模型定义。
配置
使用 ClickHouse 源的示例
模型的 SQL 将成为字典源查询:使用 HTTP 数据源的示例
使用source_type='http' (或 table 选项) 时,模型的 SQL 不会用作数据源,但 dbt 仍需要一个主体 — 请使用 select 1 作为占位符:
物化:distributed_table (experimental)
按以下步骤创建分布式表:- 创建包含 SQL 查询的临时视图,以获取正确的结构
- 基于视图创建空的本地表
- 基于本地表创建分布式表。
- 将数据插入分布式表,从而分发到各个分片,且不会发生重复。
- dbt-clickhouse 查询现在会自动包含设置
insert_distributed_sync = 1,以确保 下游增量 物化操作能够正确执行。这可能会导致某些分布式表插入操作的速度比 预期更慢。
分布式表模型示例
已生成的迁移
配置
下面列出了此物化类型特有的配置:materialization: distributed_incremental (experimental)
基于与分布式表相同思路的增量模型,主要难点在于正确处理各种增量 策略。- 追加策略 只是将数据插入分布式表。
- Delete+Insert 策略会创建分布式临时表,以便在每个分片上处理全部数据。
- 默认 (旧版) 策略 出于同样的原因,会创建分布式临时表和中间表。
Distributed 增量模型示例
已生成的迁移
Snapshot
dbt snapshots 会以类型 2 缓慢变化维度的形式记录可变模型中行随时间发生的变化,使分析人员可以”回溯”模型此前的状态。ClickHouse adapter 同时支持timestamp 和 check 两种策略。它会先在暂存表中构建 snapshot 表的新版本,再通过 EXCHANGE TABLES 将其替换上线 (若 server 不支持交换表,则改用 drop 加 rename) ,从而保证读取方始终看到的是完整的 snapshot 版本。
从 dbt 1.9 起,snapshots 在 snapshots/<name>.yml 中以 YAML 定义:
snapshots/<name>.sql 中的旧版 Jinja 写法仍然可用:
契约与约束
仅支持完全精确匹配的列类型契约。例如,如果某个契约要求列类型为 UInt32,而模型返回的是 UInt64 或其他整数类型, 该契约就会失败。 ClickHouse 也 仅 支持针对整个表/模型的CHECK 约束。不支持主键、外键、唯一约束以及
列级 CHECK 约束。
(参见 ClickHouse 关于主键 / ORDER BY 键的文档。)