在ClickHouse集群运行dbt时Mart模型报ON CLUSTER语法错误

问题现象 #

• 首次在ClickHouse集群运行dbt，所有节点成功创建表
• 第二次运行时，Mart层模型触发语法错误：

  DB::Exception: Syntax error: failed at position 201 ('ON') (line 5, col 5): ON CLUSTER

• 增量表（如fct_table）运行完全正常

原因分析 #

这是dbt-clickhouse适配器的常见问题：当Mart模型使用materialized='table'时，第二次运行dbt会尝试同步表结构，但生成的SQL错误地重复添加了ON CLUSTER子句，导致ClickHouse无法识别该语法。而增量表的同步逻辑不同，因此不受影响。

解决方案 #

方案1：给Mart模型显式指定集群配置 #

在Mart模型的config块中添加cluster参数，明确指定集群名称，让dbt生成正确的SQL：

{{
    config(
        materialized='table',
        cluster='company_cluster'
    )
}}

WITH fct_table AS (
    SELECT * FROM {{ref('fct_table')}}
)

SELECT id,
       created_at
from fct_table

方案2：全局配置Mart层的集群参数 #

直接在dbt_project.yml中为Mart层统一设置集群，不用逐个修改模型：

models:
  project:
    mart:
      +materialized: table
      +cluster: 'company_cluster'

方案3：切换Mart模型的物化类型（可选） #

如果业务场景允许，把Mart模型改成视图或者增量表，绕过当前的表结构同步逻辑：

• 改为视图：
  修改dbt_project.yml中Mart层的配置：

  models:
    project:
      mart:
        +materialized: view
  

• 改为增量表（需满足增量更新条件）：
  在Mart模型中添加增量配置：

  {{
      config(
          materialized='incremental',
          unique_key='id',
          incremental_strategy='delete+insert'
      )
  }}
  
  WITH fct_table AS (
      SELECT * FROM {{ref('fct_table')}}
  )
  
  SELECT id,
         created_at
  from fct_table
  {% if is_incremental() %}
    -- 可添加增量过滤条件，比如基于created_at或updated_at
    where created_at > (select max(created_at) from {{ this }})
  {% endif %}
  

验证方法 #

1. （可选）清理旧表：在ClickHouse客户端执行DROP TABLE IF EXISTS databasename.mart ON CLUSTER company_cluster;
2. 重新运行Mart模型：dbt run --select mart
3. 检查ClickHouse集群中是否成功生成表，且无报错

内容的提问来源于stack exchange，提问作者Atheer Abdullatif