使用dbt时SQLFluff遇Jinja增量刷新代码无警告问题求助

现象描述 #

• 未加入增量刷新Jinja代码时，SQLFluff能正常检测出SQL中的问题（比如关键字大小写、未显式别名等），示例代码：

SELECT *
FROM orders o
LEFT JOIN {{ ref('cars') }} c ON c.car_id = o.car_id

• 加入增量刷新的Jinja条件块后，SQLFluff完全不输出任何警告，示例代码：

SELECT *
FROM orders o
LEFT JOIN {{ ref('cars') }} c ON c.car_id = o.car_id

{% if is_incremental() -%}

    where o.updated_at > (select max(updated_at) from {{ this }})

{%- endif %}

• 将配置中的templater从dbt改为jinja后，警告恢复正常，但会触发宏解析错误和变量未定义的警告：

Line 6, Position 5: Found unparsable section: ',
    ,
    o.change,
    o.cost,
 ...' sqlfluff (PRS)
Undefined jinja template variable: 'my_macro_name' sqlfluff (TMP)

当前使用的.sqlfluff配置 #

[sqlfluff]
dialect = snowflake
templater = dbt
exclude_rules = ST06
runaway_limit = 10
max_line_length = 0
indent_unit = space

[sqlfluff:indentation]
tab_space_size = 4

[sqlfluff:layout:type:comma]
spacing_before = touch
line_position = trailing

[sqlfluff:rules:capitalisation.keywords] 
capitalisation_policy = lower

[sqlfluff:rules:aliasing.table]
aliasing = explicit

[sqlfluff:rules:aliasing.column]
aliasing = explicit

[sqlfluff:rules:aliasing.expression]
allow_scalar = False

[sqlfluff:rules:capitalisation.identifiers]
extended_capitalisation_policy = lower

[sqlfluff:rules:capitalisation.functions]
capitalisation_policy = lower

[sqlfluff:rules:capitalisation.literals]
capitalisation_policy = lower

[sqlfluff:rules:ambiguous.column_references]
group_by_and_order_by_style = explicit

排查与解决方法 #

1. 版本兼容性检查
   旧版本的SQLFluff和dbt组合可能存在增量模型解析bug，建议升级到最新稳定版：SQLFluff >= 2.0，dbt >= 1.3，新版本修复了大量模板解析相关的问题。

2. 强制解析全量SQL
   执行lint命令时添加--full-refresh参数，让SQLFluff模拟dbt全量刷新的上下文，解析完整的SQL代码（而非仅增量分支）：

sqlfluff lint --full-refresh models/your_target_model.sql

也可以在模型文件顶部临时添加{{ config(full_refresh=true) }}来测试，或者在配置文件中为特定模型设置全量刷新参数。

3. 开启Jinja多分支解析
   在.sqlfluff中添加dbt模板器的配置，强制解析Jinja条件语句的所有分支：

[sqlfluff:templater:dbt]
parse_all_branches = true

这个配置会让SQLFluff检查Jinja条件块的每一个分支，确保增量部分的SQL也被纳入检测范围。

4. 调整Jinja语法格式
   尝试修改增量块的语法格式，比如去掉{% if %}标签中的减号，避免可能的解析异常：

{% if is_incremental() %}
    where o.updated_at > (select max(updated_at) from {{ this }})
{% endif %}

内容的提问来源于stack exchange，提问作者Piotr K