Migration dbt-utils v1.0 : ce qui a rejoint dbt-core

Le plus grand changement de l’histoire de dbt-utils s’est produit avec la v1.0. Chaque macro cross-database — dates, chaînes, casting de types, agrégations, opérations sur les ensembles — a été supprimée de dbt_utils et déplacée vers le namespace dbt dans dbt-core. Si votre projet appelle encore dbt_utils.datediff(), vous appelez un chemin qui n’existe plus en v1.x.

Ce n’est pas une préoccupation académique. Un codebase migrant de dbt-utils 0.x vers 1.x plantera à la première exécution sans mettre à jour ces appels.

Ce qui a rejoint dbt-core

Tout ceci a été déplacé vers dbt.* et n’existe plus dans dbt_utils.* :

Date et heure : dateadd, datediff, date_trunc, last_day, current_timestamp

Chaînes : concat, length, position, replace, right, split_part, string_literal, escape_single_quotes

Casting de types : safe_cast, cast (dbt v1.8+), type_bigint, type_float, type_int, type_numeric, type_string, type_timestamp

Agrégation : any_value, bool_or, listagg

Opérations sur les ensembles : except, intersect

Autres : hash, cast_bool_to_text, array_append, array_concat, array_construct (dbt-core 1.3+), date (dbt v1.8+)

La référence complète pour ces macros se trouve dans Macros cross-database intégrées à dbt.

Ce qui a été entièrement supprimé

Une poignée de macros dbt-utils ont été supprimées sans remplacement dans dbt-core — elles sont devenues obsolètes ou ont été absorbées dans les fonctionnalités natives de dbt :

surrogate_key() → remplacé par generate_surrogate_key(). Ces deux macros ne sont pas des substituts directs : la gestion des nulls a changé. Voir dbt-utils generate_surrogate_key pour le piège.
unique_where et not_null_where (tests) → le config natif where sur les tests intégrés unique et not_null gère maintenant ce cas. Utilisez config.where à la place.
Matérialisation insert_by_period → déplacée vers le dépôt des fonctionnalités expérimentales. N’est plus dans dbt-utils.
Argument condition sur expression_is_true → remplacé par le config natif where sur le test. Tout YAML de test utilisant condition: doit être mis à jour.

Comment migrer

Étape 1 : Mettre à jour dbt-utils vers v1.x dans votre packages.yml.

packages:
  - package: dbt-labs/dbt_utils
    version: [">=1.0.0", "<2.0.0"]

Étape 2 : Trouver tous les appels de macros cross-database dbt_utils.

Recherchez dans votre projet dbt_utils.dateadd, dbt_utils.datediff, dbt_utils.date_trunc, dbt_utils.concat, dbt_utils.safe_cast et le reste de la liste déplacée. Un find-and-replace global gère la plupart des cas. Les signatures de fonctions sont identiques — seul le namespace change.

Avant : {{ dbt_utils.dateadd('day', 7, 'order_date') }}
Après :  {{ dbt.dateadd('day', 7, 'order_date') }}

Étape 3 : Gérer surrogate_key() si vous l’utilisiez.

Si votre projet utilisait l’ancienne macro surrogate_key() et que vous mettez à niveau, ajoutez d’abord ceci à dbt_project.yml pour préserver la gestion des nulls rétrocompatible :

vars:
  surrogate_key_treat_nulls_as_empty_strings: true

Sans cela, les valeurs nulles sont hachées différemment dans generate_surrogate_key(), ce qui change les valeurs des clés de substitution pour les lignes avec des nulls. Cela casse les modèles incrémentaux et les snapshots qui utilisaient l’ancienne clé. Voir dbt-utils generate_surrogate_key pour l’explication complète.

Étape 4 : Mettre à jour les tests utilisant l’argument condition:.

Si vous avez des tests expression_is_true avec un argument condition:, remplacez-le par le config natif where :

# Avant (v0.x)
- dbt_utils.expression_is_true:
    expression: "invoice__total >= invoice__tax"
    condition: "status != 'voided'"

# Après (v1.x)
- dbt_utils.expression_is_true:
    expression: "invoice__total >= invoice__tax"
    config:
      where: "status != 'voided'"

Étape 5 : Mettre à jour les appels deduplicate si vous utilisiez group_by.

L’argument group_by a été renommé en partition_by en v1.0. L’argument relation_alias a été supprimé. Et order_by est maintenant obligatoire — passez 1 si l’ordre n’a pas d’importance.

Ce qui reste dans dbt-utils

Après la migration, dbt-utils possède encore : les générateurs SQL (date_spine, deduplicate, star, union_relations, generate_surrogate_key, pivot, unpivot), les macros introspectives (get_column_values, get_relations_by_pattern, get_query_results_as_dict), les tests génériques et les macros web. Voir le Hub dbt-utils pour la portée actuelle complète.

Pourquoi cette migration a eu lieu

Les macros cross-database vivaient dans dbt-utils parce que lorsqu’elles ont été écrites, dbt-core n’avait pas de mécanisme standard pour le SQL spécifique aux adaptateurs. Une fois que dbt-core a développé adapter.dispatch() comme fonctionnalité de première classe, il était logique de déplacer les fonctions universelles vers le core où chaque projet peut les utiliser sans installer un package.

Du point de vue de la maintenance, cela signifie aussi que les corrections des fonctions cross-database arrivent maintenant dans les versions de dbt-core, qui sortent plus fréquemment et avec une couverture de tests plus large que tout package communautaire.

Si vous êtes sur un adaptateur non standard comme Databricks, vous pourriez encore avoir besoin de spark_utils dans votre configuration de dispatch pour les macros que dbt-core ne couvre pas. Voir Configuration du dispatch dbt pour configurer cela.