dbt-audit-helper supporte une approche de validation progressive : commencer par les vérifications les moins coûteuses et escalader uniquement quand elles révèlent des problèmes. Chaque étape est moins coûteuse que la suivante. Si une étape précoce montre déjà une divergence, il n’est pas nécessaire d’exécuter une comparaison complète au niveau des lignes.
La séquence
Étape 1 : Vérification du schéma
Utiliser compare_relation_columns pour vérifier que les noms de colonnes, les positions ordinales et les types de données correspondent entre les deux relations. Il s’agit de métadonnées uniquement — pas de scan de données.
{{ audit_helper.compare_relation_columns( a_relation=ref('mrt__finance__revenue'), b_relation=api.Relation.create( database='analytics_db', schema='production', identifier='mrt__finance__revenue' )) }}Si les schémas ne correspondent pas, s’arrêter ici. Les colonnes manquantes, les changements de type ou la réorganisation rendront toute comparaison en aval peu fiable. Corriger le schéma d’abord.
Étape 2 : Comptage des lignes
Utiliser compare_row_counts pour une vérification rapide de cohérence. Des comptes divergents pointent vers des différences de filtrage ou des fan-outs de jointure.
{{ audit_helper.compare_row_counts( a_relation=ref('mrt__finance__revenue'), b_relation=api.Relation.create( database='analytics_db', schema='production', identifier='mrt__finance__revenue' )) }}Les divergences de comptage des lignes se tracent presque toujours vers des différences dans les clauses WHERE, une logique de déduplication se comportant différemment, ou des JOINs produisant des cardinalités différentes.
Étape 3 : Hash rapide (Snowflake/BigQuery uniquement)
quick_are_relations_identical utilise la comparaison par hash pour un résultat pass/fail rapide. Si ça passe, c’est terminé. Pas besoin de comparaison plus approfondie.
{{ audit_helper.quick_are_relations_identical( a_relation=ref('mrt__finance__revenue'), b_relation=api.Relation.create( database='analytics_db', schema='production', identifier='mrt__finance__revenue' )) }}La variante requête quick_are_queries_identical fait la même chose avec des entrées SQL brutes.
Étape 4 : Comparaison au niveau des lignes
Si la vérification par hash échoue (ou si l’entrepôt n’est pas Snowflake/BigQuery), compare_relations effectue une validation ligne par ligne en utilisant une approche basée sur UNION.
{{ audit_helper.compare_relations( a_relation=ref('mrt__finance__revenue'), b_relation=api.Relation.create( database='analytics_db', schema='production', identifier='mrt__finance__revenue' ), exclude_columns=["_fivetran_synced"], primary_key="revenue__id", summarize=true) }}Avec summarize=true, la sortie montre des comptes : True/True (correspondances), True/False (uniquement dans A), False/True (uniquement dans B). Mettre summarize=false pour voir les lignes réellement divergentes.
Étape 5 : Isoler les colonnes problématiques
compare_which_relation_columns_differ identifie quelles colonnes causent des divergences. Exécuter avant de vérifier manuellement les colonnes une par une.
Étape 6 : Analyse approfondie de colonnes spécifiques
compare_column_values étudie une seule colonne, catégorisant chaque ligne comme : correspondance parfaite, les deux nuls, manquant dans A, manquant dans B, nul dans A seulement, nul dans B seulement, ou valeurs ne correspondent pas.
Étape 7 : Audit complet des colonnes
compare_all_columns produit un résumé par colonne. C’est la macro la mieux adaptée à l’intégration CI car elle donne une image complète en un seul passage.
Étape 8 : Classification des lignes
compare_and_classify_relation_rows étiquette chaque ligne comme identique, modifiée, ajoutée ou supprimée. Le paramètre sample_limit (défaut 20) limite le nombre de lignes d’exemple par classification.
Pourquoi cet ordre importe
L’économique est simple. Les étapes 1 à 3 sont peu coûteuses : requêtes de métadonnées, comptages en un seul passage, et agrégations de hash. Les étapes 4 à 8 impliquent des scans complets de tables, des FULL OUTER JOINs, et des UNION ALLs. Sur les grandes tables, la différence entre “vérification de schéma” et “comparaison au niveau des lignes” peut être la différence entre une requête de 2 secondes et un burn d’entrepôt de 20 minutes.
L’autre avantage est diagnostique. Si le schéma ne correspond pas, un diff au niveau des lignes sera bruité et trompeur. Si les comptes de lignes divergent, la nature du problème est déjà connue (lignes manquantes/supplémentaires) sans besoin d’inspecter des valeurs individuelles. Chaque étape réduit l’espace de recherche pour la suivante.
Appliquer le workflow
Pour le refactoring
On réécrit un CTE, on change une stratégie de jointure, ou on restructure un modèle. Pointer ref() vers le schéma dev et api.Relation.create vers la production. Exécuter la séquence progressive. Toute différence apparaît immédiatement par rapport à une base connue-bonne.
Pour la migration SQL vers dbt
Charger les tables existantes dans le même entrepôt, construire les équivalents dbt, et comparer systématiquement. Un conseil pratique de l’équipe Indicium Tech : comparer 5 colonnes à la fois, confirmer leur correspondance, puis élargir. Cela maintient une boucle de feedback serrée. Tenter de déboguer toutes les divergences simultanément mène généralement à la confusion sur quel changement a corrigé quoi.
Cette approche étend les stratégies de comparaison manuelle dans les Patterns de validation de migration dbt avec des macros automatisées et reproductibles plutôt que des requêtes EXCEPT ad hoc.
Pour les migrations ETL à grande échelle
Pour les migrations enterprise (Informatica vers dbt, ETL legacy vers dbt), le package dbt-audit-helper-ext d’Infinite Lambda étend audit-helper avec une table de log de validation, des scripts codegen pour auto-générer des macros de validation, et des critères d’acceptation basés sur des seuils : 100 % de correspondance = réussite, 99 %+ = avertissement, en dessous de 99 % = échec.