dbt-utils est le package le plus utilisé de l’écosystème dbt. Il inclut 50+ macros et tests génériques couvrant la génération SQL, l’introspection des données, la validation de qualité et la compatibilité cross-warehouse.
Ces notes couvrent dbt-utils v1.3.3, compatible avec dbt Core 1.x et dbt Fusion 2.x.
Avant de commencer
La source de confusion la plus courante avec dbt-utils est de savoir quelles macros résident encore dans le package et lesquelles ont été déplacées vers dbt-core. Depuis la v1.0, toutes les macros cross-database (dates, chaînes, casting de types) ont été déplacées vers le namespace dbt.*. Commencez par la note de migration si vous travaillez sur un codebase plus ancien ou si vous mettez à niveau depuis la v0.x.
Ordre de lecture
Migration dbt-utils v1.0 : ce qui a rejoint dbt-core
La liste complète des macros supprimées de dbt-utils et déplacées vers dbt.*, ce qui a été entièrement supprimé (ancienne surrogate_key(), unique_where, not_null_where), et le chemin de migration étape par étape. Lisez ceci en premier si vous mettez à niveau.
Générateurs SQL de dbt-utils
La partie la plus utilisée du package : date_spine, deduplicate, star, union_relations, pivot, unpivot et les helpers plus petits (group_by, safe_divide, haversine_distance, etc.). Ceux-ci génèrent du SQL à la compilation sans requêter la base de données.
dbt-utils generate_surrogate_key
La macro de clé de substitution basée sur un hash mérite sa propre note à cause du piège de gestion des nulls qui peut silencieusement casser les modèles incrémentaux lors de la migration depuis l’ancienne macro surrogate_key(). Lisez ceci avant de toucher aux clés de substitution dans un projet existant.
Macros introspectives de dbt-utils
Macros qui requêtent la base de données à la compilation : get_column_values, get_relations_by_pattern, get_query_results_as_dict, get_single_value, get_filtered_columns_in_relation. Puissantes mais nécessitent que les relations cibles existent déjà.
Tests génériques de dbt-utils
La référence complète des tests génériques avec exemples YAML. Couvre le changement de syntaxe arguments: de Fusion/dbt Core 1.10.6+, le paramètre group_by_columns pour la validation segmentée, et quand utiliser chaque test.
Macros web de dbt-utils pour le parsing d’URL
Le trio d’extraction d’URL (get_url_host, get_url_path, get_url_parameter) et les helpers de développement Jinja. De niche mais utile en analytics marketing.
Prérequis
dbt-utils doit être installé et vous devez être à l’aise avec le Jinja de base dans les modèles dbt. La note Macros dbt couvre les fondamentaux de Jinja si vous avez besoin d’un rappel sur le fonctionnement des macros sous le capot.
Pour les adaptateurs non standard (Databricks, Spark), vous pourriez avoir besoin d’une configuration de dispatch supplémentaire. Voir Configuration du dispatch dbt et la note sur les macros cross-database intégrées à dbt pour le contexte.