Détection de la dérive de la documentation dbt

Les métriques de couverture indiquent si les descriptions existent. La détection de dérive indique si elles sont encore exactes. Un projet peut afficher 95 % de couverture de documentation tandis que la moitié de ces descriptions décrivent silencieusement la mauvaise chose parce que les modèles sous-jacents ont changé.

La dérive prend trois formes, chacune nécessitant une approche de détection différente : les colonnes qui existent dans l’entrepôt mais pas dans le YAML, le SQL qui a changé sans mises à jour YAML correspondantes, et les schémas de sources qui ont évolué en amont.

Dérive au niveau des colonnes

La forme la plus concrète de dérive : l’entrepôt a des colonnes que votre YAML ne connaît pas, ou votre YAML décrit des colonnes qui n’existent plus.

dbt-checkpoint au moment du commit

Le hook check-model-has-all-columns de dbt-checkpoint capture cela pendant le développement. Il compare les colonnes de votre modèle compilé avec les colonnes de votre fichier YAML et bloque le commit si elles ne correspondent pas :

repos:
  - repo: https://github.com/dbt-checkpoint/dbt-checkpoint
    rev: v2.0.6
    hooks:
      - id: dbt-parse
      - id: check-model-has-all-columns
        files: ^models/marts

Le regex files: limite cela aux marts uniquement. Exiger une documentation complète de toutes les colonnes pour chaque modèle de staging est généralement trop agressif — ces modèles changent fréquemment et servent de détails d’implémentation internes.

La plupart des hooks dbt-checkpoint nécessitent un manifest.json récent, c’est pourquoi dbt-parse s’exécute en premier. Cela ajoute quelques secondes à chaque commit mais capture la dérive des colonnes qui autrement apparaîtrait lors des révisions de code (ou ne serait jamais détectée).

dbt-osmosis pour un audit à l’échelle du projet

Pour une vérification à l’échelle du projet au-delà de ce que les hooks pre-commit capturent, dbt-osmosis peut s’exécuter en mode audit :

dbt-osmosis yaml audit

Cela se termine avec un code non nul si le YAML d’un modèle est désynchronisé avec l’entrepôt — colonnes ajoutées, supprimées ou réordonnées. L’exécuter comme job CI planifié (pas seulement sur les PRs) capture la dérive qui s’accumule entre les pull requests, comme lorsque quelqu’un modifie une table source en dehors du workflow dbt ou lorsque la sortie compilée d’un modèle change en raison d’un changement de dépendance en amont.

La commande refactor (dbt-osmosis yaml refactor) va plus loin et corrige réellement la dérive en ajoutant les colonnes manquantes, en supprimant les colonnes périmées et en propagant les descriptions. Mais pour la détection, yaml audit vous donne le signal sans faire de changements.

Péremption basée sur Git

Une forme de dérive plus subtile se produit lorsque le SQL du modèle change mais pas sa documentation. Le YAML peut décrire les colonnes correctes, mais les descriptions sont obsolètes parce que la logique de transformation a changé.

Considérez un modèle mart mrt__marketing__customer_ltv.sql qui a été modifié dans cinq PRs depuis la dernière mise à jour de son YAML de schéma. Il y a des chances raisonnables que les descriptions soient obsolètes — une colonne qui était « revenu total » peut maintenant être « revenu total net des remboursements » après un changement SQL, mais la description dit toujours l’ancienne chose.

Vous pouvez détecter cela avec une comparaison basée sur Git. Un script qui compare les dates de dernière modification des fichiers .sql avec leurs entrées YAML correspondantes signale les modèles où le SQL a été modifié plus récemment que la documentation :

#!/bin/bash
# Trouver les modèles où le SQL a été modifié plus récemment que le YAML de schéma
for sql_file in models/**/*.sql; do
  model_name=$(basename "$sql_file" .sql)
  yaml_file=$(dirname "$sql_file")/schema.yml

  if [ -f "$yaml_file" ]; then
    sql_date=$(git log -1 --format="%at" -- "$sql_file")
    yaml_date=$(git log -1 --format="%at" -- "$yaml_file")

    if [ "$sql_date" -gt "$yaml_date" ]; then
      echo "PÉRIMÉ: $model_name (SQL mis à jour le $(date -d @$sql_date +%Y-%m-%d), YAML dernièrement touché le $(date -d @$yaml_date +%Y-%m-%d))"
    fi
  fi
done

C’est une heuristique, pas une preuve de péremption. Un changement SQL qui reformate uniquement les espaces ne rend pas la documentation périmée. Les modèles avec le plus grand écart entre les dates de modification SQL et YAML sont les candidats les plus probables pour des descriptions obsolètes. Exécuter ceci comme job planifié hebdomadaire et publier les résultats sur Slack ou un tableau de bord maintient la péremption visible sans bloquer aucun workflow.

Limitations de l’approche Git

Le script ci-dessus traite chaque fichier YAML de schéma comme une unité. Si vos fichiers YAML contiennent plusieurs modèles (ce qui est courant), un changement dans la section d’un modèle met à jour le timestamp du fichier pour tous les modèles dans ce fichier. Cela signifie que le script peut manquer la péremption pour les modèles qui partagent un fichier YAML avec un modèle récemment documenté.

Une détection plus précise analyserait le YAML et comparerait les sections par modèle, mais la comparaison simple au niveau du fichier capture les cas les plus courants et est triviale à mettre en place.

Dérive de schéma pour les sources

Les tables sources se situent en dehors du contrôle de votre projet dbt. Quelqu’un dans l’équipe applicative ajoute une colonne à la table users, change un type de colonne, ou supprime un champ — et vos définitions de source dbt n’en savent rien.

La fraîcheur des sources comme signal proxy

dbt source freshness ne détecte pas directement les changements de schéma, mais fournit un signal proxy utile. Si une source n’a pas été rafraîchie selon le calendrier, les données qui circulent dans vos modèles peuvent ne pas correspondre à ce que la documentation décrit. Les échecs de fraîcheur sont un signal pour enquêter si le schéma de la source a également changé.

Détection dédiée de la dérive de schéma

dbt_schema_drift détecte quand les schémas de sources changent en amont. Il compare le schéma actuel de l’entrepôt avec vos définitions de sources déclarées et signale les différences — nouvelles colonnes, colonnes supprimées, types modifiés.

C’est particulièrement important pour les sources parce que :

• Les changements de sources se produisent en dehors du processus de PR de votre équipe
• Aucun hook pre-commit ne peut capturer les changements de schéma externes
• L’écart entre un changement de schéma de source et sa découverte peut être de semaines ou de mois
• La documentation écrite contre l’ancien schéma devient immédiatement trompeuse

Exécuter la détection de dérive de schéma comme job CI planifié (quotidien ou à chaque exécution du pipeline) vous donne un avertissement précoce lorsque les sources changent. Lorsque la dérive est détectée, vous pouvez mettre à jour le YAML de source, propager les changements en aval avec dbt-osmosis, et vérifier si des descriptions doivent être mises à jour.

Superposer la détection de dérive

Aucun outil ne capture toutes les formes de dérive. Une configuration pratique les combine :

Les hooks pre-commit capturent la dérive à mesure qu’elle est introduite. Les jobs planifiés capturent la dérive qui s’accumule entre les PRs ou provient de changements de schéma externes.