ServicesÀ proposNotesContact Me contacter →
EN FR
Note

Écrire des macros dbt réutilisables

Une carte des notes du jardin sur la conception, le nommage, la documentation, les tests et l'évolution des macros dbt — du moment où les extraire jusqu'à la gestion des changements incompatibles.

Planté
dbtdata modelingdata engineering

Ce hub cartographie les notes sur la conception des macros dbt : quand extraire, comment délimiter la portée, les conventions de nommage, la documentation, les tests et la gestion des changements incompatibles. Les notes peuvent être lues dans l’ordre ou consultées pour des questions spécifiques.

Prérequis

Ces notes supposent que vous comprenez déjà le fonctionnement des macros dbt au niveau syntaxique — les fondamentaux Jinja, le flag execute, les objets de contexte et le pattern dispatch. Si vous débutez avec les macros, commencez d’abord par dbt Macros.

Ordre de lecture

  1. Règle des trois pour les macros dbt — quand extraire une macro par rapport à quand laisser le code inline. La discipline qui prévient l’abstraction prématurée.

  2. Macros dbt à responsabilité unique — une fois que vous avez décidé d’extraire, comment délimiter la portée. Le signal d’alarme d’explosion de paramètres et le pattern de composition.

  3. Conventions de nommage des macros dbt — préfixes de verbes, noms descriptifs, underscore pour les helpers internes, une macro par fichier. Les noms sont la documentation la moins chère que vous ayez.

  4. Macros dbt — structure et organisation des dossiers, plus les fondamentaux Jinja si vous avez besoin d’un rappel sur dispatch, les gardes execute et les objets de contexte.

  5. Documentation YAML des macros dbt — pourquoi _macros.yml surpasse les commentaires, et comment rédiger des descriptions que les développeurs utilisent réellement (exemples d’utilisation, pas de descriptions abstraites d’arguments).

  6. Patterns de test des macros dbt — modèles de tests d’intégration, tests unitaires natifs (dbt 1.8+) et le workflow de débogage compile-and-inspect.

  7. Pattern de dépréciation des macros dbt — dépréciation progressive avec exceptions.warn() quand le comportement d’une macro doit changer après que des modèles en dépendent.

Laisser trois lignes de code similaires inline plutôt que d’extraire une macro est parfois le bon choix. La lisibilité et la maintenabilité sont les critères, pas l’élimination de la duplication.