无法调用dbt_utils包的union_relations宏，求排查方案

可能的原因及解决办法 #

1. dbt-core与dbt_utils版本不兼容 #

dbt_utils 1.1.1要求dbt-core版本至少为1.3.x，若你的dbt-core版本低于此阈值，会导致宏无法正常加载解析。

• 解决步骤：
  • 执行dbt --version查看当前dbt-core版本
  • 若版本不匹配，要么升级dbt-core到1.3.x及以上，要么将dbt_utils版本降级至与当前dbt-core兼容的版本（比如dbt-core 1.2.x对应dbt_utils 1.0.x）

2. 宏调用方式不符合版本要求 #

dbt_utils 1.0+版本对union_relations的调用逻辑有调整，旧的带前缀调用方式可能失效。

• 解决步骤：
  • 尝试去掉dbt_utils.前缀，直接调用：{{ union_relations(relations=[ref('src'), ref('src2'), ref('src3'), ref('src4'), ref('src5')]) }}
  • 检查dbt_project.yml的macro-paths配置，确保packages宏路径被包含：

    macro-paths: ["macros", "dbt_packages/dbt_utils/macros"]
    

3. dbt_packages目录未被正确识别 #

即便执行了dbt deps，也可能存在缓存残留、权限问题或配置缺失导致宏无法被读取。

• 解决步骤：
  • 执行dbt clean && dbt deps，清理旧缓存后重新安装依赖
  • 检查dbt_project.yml的dispatch配置，确保dbt_utils宏被正确调度：

    dispatch:
      - macro_namespace: dbt_utils
        search_order: ['你的项目名称', 'dbt_utils']
    

  • 确认dbt_packages/dbt_utils/macros/sql/union.sql文件完整，未被篡改或损坏

4. 同名宏冲突或加载顺序异常 #

项目自定义宏中若存在同名的union_relations，会覆盖dbt_utils的宏；或宏加载顺序异常导致调用时宏未完成加载。

• 解决步骤：
  • 检查项目自身macros目录，若有同名宏，重命名或删除
  • 在模型文件开头添加显式导入：{% import 'dbt_utils' as dbt_utils %}，确保宏模块被正确加载

内容的提问来源于stack exchange，提问作者Daniel Weigel