dbt-audit-helper is a dbt Labs package for comparing two relations — validating refactors, proving migration equivalence, and catching regressions in CI. It provides macros that progress from cheap metadata checks to expensive row-level diffs, so you only burn warehouse compute when cheaper checks already indicate a problem.
Core Notes
-
dbt-audit-helper Progressive Validation — The methodology: start with schema checks, escalate through row counts, hash checks, and row-level diffs. Why ordering matters for cost and diagnostics.
-
dbt-audit-helper Macro Reference — Every macro documented:
compare_relation_columns,compare_row_counts,quick_are_relations_identical,compare_relations,compare_queries,compare_which_relation_columns_differ,compare_column_values,compare_all_columns, andcompare_and_classify_relation_rows. Parameters, output format, platform support, gotchas. -
dbt-audit-helper CI/CD Integration — Using
compare_all_columnsas a CI test, dbt Cloud PR job configuration, dbt Core with GitHub Actions (--defer --state),--store-failuresfor diagnosis, and handling expected vs. unexpected changes.
Related Topics
-
Floating-Point Precision in Data Comparison — Why exact equality fails on floating-point values and how to handle it with ROUND/CAST before comparing. Applies to audit-helper, EXCEPT queries, and any comparison approach.
-
Data Comparison Tool Landscape — When to use audit-helper vs. Elementary, dbt-expectations, Datafold, or Soda. Decision matrix by scenario.
Connections
dbt-audit-helper sits within the broader data quality validation stack. It occupies the “point-in-time comparison” niche — proving that a change didn’t break output. For ongoing monitoring, see Elementary for dbt. For rule-based validation, see the dbt Testing Taxonomy.
For migration-specific workflows (parallel execution, phased cutover, sign-off criteria), see dbt Migration Validation Patterns, which covers the broader process that audit-helper macros automate.