ServicesÀ proposNotesContact Me contacter →
EN FR
Note

Référence des macros dbt-audit-helper

Référence de chaque macro dbt-audit-helper — paramètres, format de sortie, support des plateformes, et notes d'utilisation pratiques.

Planté
dbtdata qualitytesting

dbt-audit-helper est maintenu par dbt Labs, actuellement en version 0.13.0. Il est compatible Fusion (require-dbt-version: >=1.2.0, <3.0.0), dépend de dbt-utils, et supporte Snowflake, BigQuery, Postgres et Redshift. Les macros rapides basées sur le hash sont limitées à Snowflake et BigQuery.

Toutes les macros suivent un pattern cohérent : elles acceptent deux relations (ou requêtes) et retournent un résultat de comparaison. Le workflow de validation progressive explique l’ordre dans lequel les utiliser.

Macros de schéma et de comptage

compare_relation_columns

Compare les métadonnées de schéma : noms de colonnes, positions ordinales et types de données. Pas de scan de données — métadonnées uniquement.

{{ 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'
    )
) }}

Cas d’usage : Exécuter en premier dans tout workflow de comparaison. Détecte les colonnes manquantes, les changements de type et la réorganisation des colonnes avant de dépenser du compute sur la comparaison des données.

compare_row_counts

Comparaison simple du nombre de lignes entre deux relations. Ajouté en v0.11.0 (mars 2024).

{{ 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'
    )
) }}

Cas d’usage : Vérification rapide de cohérence après validation du schéma. Des comptes divergents pointent vers des différences de filtrage ou de jointure.

Macros de hash rapides

quick_are_relations_identical

Utilise la comparaison par hash pour un résultat pass/fail rapide. Snowflake et BigQuery uniquement.

{{ 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'
    )
) }}

Cas d’usage : Si ça passe, c’est terminé — pas besoin de comparaison plus approfondie. Si ça échoue, passer à compare_relations.

Il existe aussi quick_are_queries_identical pour comparer des instructions SELECT SQL brutes.

Macros de comparaison au niveau des lignes

compare_relations

La macro principale. 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
) }}

Paramètres :

  • exclude_columns — liste des colonnes à ignorer (utile pour les colonnes de métadonnées ETL)
  • primary_key — la clé de jointure pour la correspondance des lignes
  • summarize — true (défaut) pour les comptes/pourcentages ; false pour les données brutes de lignes avec les flags in_a/in_b

Sortie avec summarize=true :

  • True/True : lignes dans les deux relations (correspondances)
  • True/False : lignes uniquement dans A
  • False/True : lignes uniquement dans B

compare_queries

Identique à compare_relations mais accepte des instructions SELECT SQL brutes. L’utiliser quand il est nécessaire de filtrer, renommer ou retyper des colonnes avant la comparaison. Particulièrement utile pour gérer les problèmes de précision en virgule flottante :

{{ audit_helper.compare_queries(
    a_query="SELECT revenue__id, ROUND(revenue__amount, 2) AS revenue__amount FROM " ~ ref('mrt__finance__revenue'),
    b_query="SELECT revenue__id, ROUND(revenue__amount, 2) AS revenue__amount FROM analytics_db.production.mrt__finance__revenue",
    primary_key="revenue__id"
) }}

Macros au niveau des colonnes

compare_which_relation_columns_differ

Identifie quelles colonnes causent des divergences au niveau des lignes. Ajouté en v0.12.0 (juin 2024).

{{ audit_helper.compare_which_relation_columns_differ(
    a_relation=ref('mrt__finance__revenue'),
    b_relation=api.Relation.create(
      database='analytics_db',
      schema='production',
      identifier='mrt__finance__revenue'
    ),
    primary_key_columns=['revenue__id']
) }}

Cas d’usage : Exécuter après que compare_relations montre des divergences mais avant de vérifier manuellement les colonnes une par une.

compare_column_values

Plonge en profondeur dans les valeurs d’une seule colonne, jointurée sur une clé primaire.

{{ audit_helper.compare_column_values(
    a_query="SELECT revenue__id, revenue__amount FROM " ~ ref('mrt__finance__revenue'),
    b_query="SELECT revenue__id, revenue__amount FROM analytics_db.production.mrt__finance__revenue",
    primary_key="revenue__id",
    column_to_compare="revenue__amount"
) }}

Catégories de sortie : correspondance parfaite, les deux nuls, manquant dans A, manquant dans B, nul dans A seulement, nul dans B seulement, valeurs ne correspondent pas.

Piège : La méthode .print_table() n’est pas compatible avec dbt Cloud. Utiliser {{ log(result, info=true) }} comme solution de contournement.

compare_all_columns

Compare toutes les colonnes entre deux relations avec un résumé par colonne : perfect_match, null_in_a, null_in_b, missing_from_a, missing_from_b et conflicting_values.

{{ audit_helper.compare_all_columns(
    a_relation=ref('mrt__finance__revenue'),
    b_relation=api.Relation.create(
      database='analytics_db',
      schema='production',
      identifier='mrt__finance__revenue'
    ),
    primary_key_columns=['revenue__id']
) }}

C’est la macro la mieux adaptée à l’intégration CI. Créer un test qui filtre sur les conflits :

models:
  - name: mrt__finance__revenue
    data_tests:
      - dbt_utils.expression_is_true:
          expression: "conflicting_values = 0"
          where: "1=1"

compare_and_classify_relation_rows

Ajouté en v0.12.0, marqué “v0, sujet à changement.” Classifie chaque ligne comme identique, modifiée, ajoutée ou supprimée.

{{ audit_helper.compare_and_classify_relation_rows(
    a_relation=ref('mrt__finance__revenue'),
    b_relation=api.Relation.create(
      database='analytics_db',
      schema='production',
      identifier='mrt__finance__revenue'
    ),
    primary_key_columns=['revenue__id'],
    columns=['revenue__amount', 'revenue__currency', 'revenue__booked_at'],
    sample_limit=20
) }}

Le paramètre sample_limit (défaut 20) limite les lignes d’exemple par classification. La variante requête est compare_and_classify_query_results.

Limitations

Exigence de clé primaire. La plupart des macros ont besoin d’une clé primaire unique et non nulle. S’assurer que les modèles passent les tests unique et not_null avant d’exécuter des comparaisons. Sans clé fiable, les macros basées sur la jointure produisent des résultats trompeurs.

Performance sur les grandes tables. Les macros utilisent FULL OUTER JOIN et UNION ALL sous le capot — des scans complets de tables. Utiliser d’abord quick_are_relations_identical, filtrer avec des clauses WHERE, ou comparer des sous-ensembles délimités par date avant d’exécuter des comparaisons complètes.

Un modèle à la fois. Contrairement à des outils comme Datafold qui découvrent automatiquement les modèles affectés, audit-helper requiert une configuration manuelle par modèle. Acceptable pour une validation ciblée, fastidieux pour des migrations couvrant des dizaines de modèles.

Compatibilité dbt Cloud. La méthode .print_table() ne fonctionne pas dans l’IDE dbt Cloud. Utiliser {{ log(result, info=true) }} à la place.