dbt-audit-helper 迁移对等校验

要解决的具体问题

在 dbt 项目重构或替换数据源时，团队常默认“新旧模型迁移是对等的”，但实际可能隐藏三类风险：

• 列结构不一致：列名相同但顺序不同，或某些列仅存在于新旧关系中的一侧。
• 数据语义偏差：列名相同但行值分布、聚合结果存在差异，却未被常规 dbt 构建捕获。
• 验证滞后：直到部署后下游报表异常，才发现迁移对等假设不成立，回滚成本高。

技能如何工作

该技能允许代理在部署前主动运行三类验证操作，将“信任对等”转化为“验证对等”：

• 执行 dbt 对等检查：调用 dbt-audit-helper 的比较宏，直接在 dbt 环境中对比新旧模型或关系。
• 关系差异比较：识别两侧关系的列集合差异，明确哪些列缺失或多余，避免“隐式忽略”。
• 行或值比较：通过行数统计、值分布或聚合结果对比，验证数据内容层面的一致性，而非仅看结构。

关键操作步骤包括：

• 构造比较用的列列表时，使用 dbt_utils.get_filtered_columns_in_relation，既能排除少量无关列，也能处理列数较多的情况。
• 若某些列仅存在于一侧关系，通过 exclude_columns 参数明确排除，避免比较失败或结果误导。

适用边界与注意点

该技能的有效性依赖两个前提：两侧关系的列名必须完全相同（顺序可不同）；同时需要预先配置好 dbt Core、仓库凭证和 dbt-audit-helper 包。

需注意：

• 若列名不一致（如大小写、前缀差异），需先在 dbt 模型中统一列名后再比较，否则验证结果无效。
• 它不能替代完整的数据质量测试，仅聚焦于“迁移对等”的即时验证，长期数据一致性仍需结合其他测试策略。

从内容到行动

建议将验证步骤嵌入迁移前的 CI 流程，每次修改 dbt 模型或数据源时自动运行该技能，避免对等假设未经验证就进入生产环境。