Quand écrire des matérialisations dbt personnalisées

Les matérialisations personnalisées ajoutent une charge de maintenance réelle. Ce sont du code Jinja qui s’intercale entre dbt et l’entrepôt, invisible pour la plupart des membres de l’équipe, et qui plante d’une façon plus difficile à déboguer que les modèles habituels. Avant d’en écrire une, épuiser les options intégrées. La plupart des situations du type « j’ai besoin d’une matérialisation personnalisée » sont en réalité des situations du type « je n’ai pas pleinement exploré ce que dbt fait déjà ».

Ce que dbt gère déjà

La matérialisation incrémentale est plus flexible qu’elle n’y paraît, et couvre la majorité des cas où l’on envisage d’abord d’aller sur du personnalisé.

Le comportement append-only est intégré. Définir incremental_strategy='append' pour insérer des lignes sans merger ni mettre à jour. Ajouter full_refresh: false pour empêcher --full-refresh de supprimer la table. Cela gère les logs d’audit, les flux d’événements et toute table où les lignes historiques ne doivent jamais être touchées.

{{ config(
    materialized='incremental',
    incremental_strategy='append',
    full_refresh=false
) }}

Les remplacements au niveau partition sont également intégrés. La stratégie insert_overwrite dans dbt-bigquery remplace des partitions entières au lieu de merger des lignes individuelles. Elle construit une table temporaire, identifie les partitions affectées et les échange de façon atomique.

{{ config(
    materialized='incremental',
    incremental_strategy='insert_overwrite',
    partition_by={'field': 'event_date', 'data_type': 'date'}
) }}

La stratégie delete+insert gère le remplacement au niveau ligne par clé unique. Entre ces trois stratégies et la config full_refresh, la plupart des patterns incrémentaux sont couverts sans code personnalisé.

Les alternatives à épuiser en premier

Avant d’écrire une matérialisation personnalisée, parcourir ces options dans l’ordre :

Les post-hooks gèrent de nombreuses opérations post-build. Si un seul GRANT après le build, un ALTER TABLE, ou une politique de sécurité sur un modèle spécifique est nécessaire, un post-hook est plus simple :

{{ config(
    materialized='table',
    post_hook="GRANT SELECT ON {{ this }} TO 'group:analysts@company.com'"
) }}

Les post-hooks deviennent insuffisants quand le pattern est complexe (plusieurs instructions avec des guillemets imbriqués), quand il se répète sur de nombreux modèles (copier-coller des blocs de SQL), ou quand l’ordre des opérations importe d’une façon que les hooks ne peuvent pas contrôler.

Les macros dans le SQL du modèle peuvent générer des instructions complexes sans toucher aux matérialisations. Une macro qui construit une instruction MERGE avec une logique de résolution de conflits personnalisée garde la complexité visible dans le fichier du modèle plutôt que cachée dans une matérialisation.

Les hooks on-run-end gèrent les opérations à l’échelle du projet qui doivent se produire après chaque exécution dbt, comme la révocation de permissions temporaires ou le nettoyage de schémas staging.

Quand les matérialisations personnalisées valent l’effort

Écrire une matérialisation personnalisée quand :

Le pattern est suffisamment complexe pour que le copier-coller soit source d’erreurs. Une table sécurisée avec trois politiques d’accès aux lignes, huit descriptions de colonnes et des tags de masquage de données représente une douzaine d’instructions SQL en post-hooks. Ce n’est pas maintenable. Une matérialisation qui lit un dict de config et génère le DDL approprié, si.
Le comportement est nécessaire sur de nombreux modèles. Si trente modèles ont besoin du même pattern de swap sans interruption de service, une matérialisation offre un seul endroit pour maintenir la logique au lieu de trente ensembles de post-hooks.
Les matérialisations intégrées vont activement à l’encontre des besoins. La matérialisation table standard supprime et recrée. Si l’ancienne table doit rester interrogeable jusqu’à ce que la nouvelle soit validée et prête, le processus d’échange doit être contrôlé manuellement.
Une validation avant remplacement est nécessaire. Vérifier le nombre de lignes, la compatibilité du schéma ou les règles métier avant de valider un échange de table n’est pas quelque chose que les post-hooks peuvent faire — au moment où un post-hook s’exécute, l’ancienne table a déjà disparu.

Quand passer son chemin sur la matérialisation personnalisée

L’ignorer quand :

Un post-hook résout le problème. Une ou deux instructions DDL supplémentaires après un build ne justifient pas une matérialisation complète.
Seuls un ou deux modèles ont besoin du comportement. La charge de compréhension et de maintenance d’une matérialisation personnalisée ne vaut pas la peine pour des cas isolés. Mettre la logique dans une macro ou un post-hook et passer à autre chose.
On est la seule personne qui la maintiendra. Les matérialisations personnalisées font partie du code dbt le plus difficile à déboguer. Si personne d’autre dans l’équipe ne maîtrise suffisamment Jinja pour résoudre les pannes de matérialisation, on crée un point de défaillance unique dans le projet.
Le comportement s’exprime mieux comme une macro. Si ce dont on a réellement besoin est une instruction MERGE personnalisée ou une syntaxe CREATE TABLE spécifique, l’écrire comme une macro que le modèle appelle directement. On obtient la réutilisabilité sans la surcharge de la matérialisation.

Le spectre de complexité

Il faut le penser comme un spectre du plus simple au plus complexe :

SQL inline — comportement ponctuel dans un seul modèle
Post-hooks — opérations post-build simples, une à deux instructions
Macros — génération SQL réutilisable, appelée explicitement depuis les modèles
Matérialisations personnalisées — contrôle complet du cycle de vie, de nombreux modèles, opérations complexes en plusieurs étapes

Chaque niveau ajoute puissance et charge de maintenance. Passer à un niveau supérieur seulement quand les niveaux inférieurs ne peuvent genuinement pas résoudre le problème. La structure en six étapes d’une matérialisation n’est pas difficile à comprendre, mais chaque abstraction ajoutée est une abstraction que quelqu’un devra déboguer à 2 h du matin quand le pipeline tombe en panne.

Le pattern de table sans interruption est la plus simple des matérialisations personnalisées courantes et un bon point de départ pour apprendre la structure. Il résout un problème clair et concret (interruptions pendant le build et échanges non validés) et suit l’anatomie standard sans trop de parties mobiles. Une fois à l’aise avec cela, le pattern de table sécurisée ajoute plus d’opérations post-build en suivant les mêmes principes.