Override de matérialisation Elementary pour dbt 1.8+

Sur dbt 1.8+, Elementary nécessite une macro d’override de matérialisation dans le projet consommateur. Sans elle, les tests s’exécutent sans erreur mais elementary_test_results reste vide — un échec silencieux qui n’est pas remonté par la sortie dbt ou Elementary.

Ce qui a changé dans dbt 1.8

Avant dbt 1.8, les packages pouvaient librement surcharger des matérialisations intégrées comme test. Elementary utilisait cela pour intercepter chaque exécution de test et capturer le résultat dans ses tables de métadonnées.

dbt 1.8 a resserré ces règles. Les packages ne peuvent plus surcharger les matérialisations intégrées à moins que le projet consommateur ne l’autorise explicitement. Le flag pour cela est require_explicit_package_overrides_for_builtin_materializations. La documentation d’Elementary indique de le mettre à False, ce qui réactive le comportement d’override.

Mais définir le flag seul ne suffit pas. Il faut également déclarer l’override dans le répertoire macros de votre propre projet. Le modèle de dbt 1.8 est que le projet (pas le package) contrôle quels overrides sont actifs. Si vous n’écrivez pas la macro dans votre projet, l’override d’Elementary ne s’active pas, même avec le flag défini.

Les deux éléments requis

Dans dbt_project.yml :

flags:
  require_explicit_package_overrides_for_builtin_materializations: False
  source_freshness_run_project_hooks: True

Le second flag (source_freshness_run_project_hooks) garantit que les hooks on-run-end se déclenchent après les commandes dbt source freshness, pas seulement après dbt run et dbt test. Sans lui, les vérifications de fraîcheur ne peuplent pas les tables d’Elementary.

Puis créez macros/elementary_materialization.sql dans votre projet :

-- Pour BigQuery et la plupart des autres adaptateurs
{% materialization test, default %}
  {{ return(elementary.materialization_test_default()) }}
{% endmaterialization %}

Pour Snowflake, utilisez plutôt la version spécifique à l’adaptateur :

{% materialization test, adapter='snowflake' %}
  {{ return(elementary.materialization_test_snowflake()) }}
{% endmaterialization %}

N’utilisez pas les deux versions dans le même fichier. Choisissez celle correspondant à votre entrepôt.

Pourquoi l’échec silencieux est important

Le mode d’échec sans cette macro est genuinement difficile à diagnostiquer. L’exécution de dbt test réussit. Le package Elementary est installé. Le schéma elementary existe dans votre entrepôt avec toutes les bonnes tables. Mais lorsque vous exécutez edr report, vous ne voyez aucun résultat de test, ou uniquement des résultats de l’étape dbt run sans rien provenant des tests.

L’indice est de vérifier elementary_test_results directement :

SELECT COUNT(*) FROM your_schema_elementary.elementary_test_results

Si cela retourne zéro après avoir exécuté dbt test, l’override de matérialisation est presque certainement le problème.

La séquence de correction une fois la macro ajoutée :

dbt deps
dbt run --select elementary --full-refresh
dbt test

Le --full-refresh garantit que les tables d’Elementary sont recréées proprement. Exécutez ensuite les tests pour repeupler les résultats et vérifiez que le comptage dans elementary_test_results est maintenant non-zéro.

Vérification du travail

Après avoir ajouté la macro et exécuté la séquence, vous devriez voir des lignes dans elementary_test_results pour chaque test exécuté. Chaque ligne capture le nom du test, le modèle, le statut du résultat, le temps d’exécution et l’ID d’invocation. Si vous voyez des lignes, l’override fonctionne.

La note Elementary Setup Troubleshooting couvre les autres modes d’échec et leurs correctifs.