Elementary pour dbt : guide d'installation complet

Vos tests dbt passent, mais quelque chose ne tourne pas rond. Le nombre de lignes a chuté de 40 % pendant la nuit. Une colonne qui n’était jamais nulle contient soudain des milliers de valeurs manquantes. Les données sont arrivées avec trois heures de retard. Les tests natifs dbt détectent ce que vous leur dites de détecter. Ils ne remarquent pas l’inattendu.

Elementary comble cette lacune. C’est un outil d’observabilité natif dbt qui ajoute la détection d’anomalies, le suivi historique et les alertes à votre workflow existant. Pas de plateforme séparée à gérer, pas d’intégrations complexes. Vos métadonnées d’observabilité vivent dans votre warehouse, interrogeables comme n’importe quelle autre table.

Ce guide détaille l’installation et la configuration, principalement sur BigQuery (avec un aperçu de Snowflake et Databricks).

Comment fonctionne Elementary

Elementary se compose de deux éléments qui fonctionnent ensemble.

Le package dbt s’installe comme n’importe quel autre package dbt. Il crée des tables de métadonnées dans votre warehouse et utilise des hooks on-run-end pour capturer les artefacts après chaque exécution dbt. Les durées d’exécution des modèles, les résultats de tests et les informations de schéma alimentent des tables qui vous appartiennent.

Le CLI Elementary (edr) est un outil Python qui lit ces tables dans votre warehouse. Il génère des rapports d’observabilité HTML, envoie des alertes vers Slack ou Teams, et exécute des tests de détection d’anomalies. Le CLI se connecte directement à votre warehouse via son propre profil.

Le flux de données ressemble à ceci :

dbt run/test → hooks on-run-end → INSERT dans les tables Elementary → le CLI lit les tables → rapports/alertes

Cette architecture rend vos données d’observabilité portables. Vous pouvez les interroger directement, construire des dashboards personnalisés ou migrer vers un autre outil sans perdre l’historique.

Installer le package dbt

Ajoutez Elementary à votre packages.yml :

packages:
  - package: elementary-data/elementary
    version: 0.21.0

Configurez le schéma dans dbt_project.yml :

models:
  elementary:
    +schema: "elementary"

Si vous utilisez dbt 1.8 ou une version ultérieure, deux flags supplémentaires sont nécessaires :

flags:
  require_explicit_package_overrides_for_builtin_materializations: False
  source_freshness_run_project_hooks: True

L’override de matérialisation (dbt 1.8+)

C’est l’étape que la plupart des guides survolent, et c’est là que beaucoup d’installations échouent silencieusement.

dbt 1.8 a modifié le fonctionnement des matérialisations de packages. Elementary a besoin d’overrider la matérialisation de test pour capturer correctement les résultats. Sans cet override, vos tests s’exécutent mais les tables Elementary restent vides.

Créez macros/elementary_materialization.sql :

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

Si vous êtes sur Snowflake, utilisez la version spécifique Snowflake :

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

Lancer l’installation

dbt deps                        # Installer le package
dbt run --select elementary     # Créer les tables Elementary
dbt test                        # Exécuter les tests pour alimenter les résultats

Après cette étape, vérifiez votre warehouse. Vous devriez voir un schéma elementary (ou celui que vous avez configuré) avec des tables comme elementary_test_results, dbt_run_results et dbt_models.

Configuration BigQuery

Le CLI a besoin de son propre profil de connexion pour lire votre warehouse. Ce profil est distinct de votre profil dbt.

Générez un template :

dbt run-operation elementary.generate_elementary_cli_profile

Cette commande produit du YAML à ajouter dans ~/.edr/profiles.yml. Voici un exemple complet pour BigQuery :

elementary:
  outputs:
    default:
      type: bigquery
      method: oauth  # ou service-account
      project: your-project-id
      dataset: your_schema_elementary
      location: US  # Obligatoire pour Elementary
      threads: 4

Le paramètre location

Elementary exige le paramètre location pour les connexions BigQuery. Cela piège les utilisateurs qui copient directement leur profil dbt. dbt traite la location comme optionnelle et la déduit, mais le CLI d’Elementary a besoin qu’elle soit explicite.

Si vous voyez des erreurs liées à la location ou à la région, c’est généralement la raison.

Permissions requises

Le compte de service ou l’utilisateur qui exécute le CLI a besoin de :

BigQuery Data Viewer sur le dataset Elementary
BigQuery Metadata Viewer sur vos datasets dbt
BigQuery Resource Viewer sur vos datasets dbt
BigQuery Job User sur le projet

Pour une configuration avec un compte de service, le profil ressemble à ceci :

elementary:
  outputs:
    default:
      type: bigquery
      method: service-account
      project: your-project-id
      dataset: your_schema_elementary
      keyfile: /path/to/service-account.json
      location: US
      threads: 4

Configuration Snowflake et Databricks

Snowflake

Snowflake prend en charge l’authentification par mot de passe ou par paire de clés :

elementary:
  outputs:
    default:
      type: snowflake
      account: your_account_id
      user: elementary_user
      role: elementary_role
      private_key_path: /path/to/private.key
      database: analytics
      warehouse: transforming
      schema: elementary
      threads: 4

Accordez les permissions nécessaires :

CREATE ROLE elementary_role;
GRANT USAGE ON WAREHOUSE transforming TO ROLE elementary_role;
GRANT USAGE ON DATABASE analytics TO ROLE elementary_role;
GRANT USAGE ON SCHEMA analytics.elementary TO ROLE elementary_role;
GRANT SELECT ON ALL TABLES IN SCHEMA analytics.elementary TO ROLE elementary_role;
GRANT SELECT ON FUTURE TABLES IN SCHEMA analytics.elementary TO ROLE elementary_role;

Databricks

Pour Unity Catalog, vous devez spécifier le paramètre catalog pour le namespace à trois niveaux :

elementary:
  outputs:
    default:
      type: databricks
      host: your-workspace.cloud.databricks.com
      http_path: /sql/1.0/warehouses/your-warehouse-id
      token: your-personal-access-token
      catalog: your_catalog
      schema: elementary
      threads: 4

Utilisez des service principals pour les déploiements en production. Les clusters partagés peuvent provoquer des erreurs de permissions car le CLI tente d’écrire dans les répertoires de packages. Utilisez des clusters mono-utilisateur ou ajoutez le flag --update-dbt-package false.

Installation du CLI et premier rapport

Installez le CLI avec votre adapter :

pip install 'elementary-data[bigquery]'
# ou
pip install 'elementary-data[snowflake]'
# ou
pip install 'elementary-data[databricks]'

Générez votre premier rapport :

edr report

Cette commande crée un fichier HTML dans ./edr_target/ par défaut. Ouvrez-le dans un navigateur pour voir :

Les résultats de tests avec le nombre de succès/échecs/avertissements
L’historique d’exécution des modèles et leurs durées
Le lineage des données depuis votre manifest
Les résultats de détection d’anomalies (une fois ces tests ajoutés)

Flags utiles pour la génération de rapports :

Flag	Utilité
`--days-back 7`	Limiter aux 7 derniers jours de données
`--select last_invocation`	Afficher uniquement la dernière exécution
`--disable-samples`	Désactiver l’échantillonnage de données (si enjeux PII)

Résolution des problèmes courants

Rapport vide ou aucun résultat de test

La table elementary_test_results est vide même après avoir exécuté des tests.

Cause : le package ne capture pas les résultats, généralement parce que l’override de matérialisation est manquant (dbt 1.8+) ou que le package n’a pas été installé correctement.

Solution :

Vérifiez que la macro de matérialisation existe dans votre projet
Exécutez dbt deps pour réinstaller les packages
Exécutez dbt run --select elementary --full-refresh pour recréer les tables
Relancez dbt test

”command not found: edr”

Le CLI n’est pas dans votre PATH.

Solution : installez-le dans un environnement virtuel et activez-le :

python3 -m venv venv_elementary
source venv_elementary/bin/activate
pip install 'elementary-data[bigquery]'

Ou utilisez python -m edr report pour l’exécuter sans modifier le PATH.

Erreurs de location BigQuery

Erreurs mentionnant location, région ou multi-région.

Solution : ajoutez le paramètre location à votre profil Elementary. Utilisez US, EU ou votre région spécifique.

Tables créées en tant que vues

Les tables Elementary apparaissent comme des vues au lieu de tables incrémentales, ce qui dégrade les performances.

Cause : une configuration de matérialisation conflictuelle dans votre projet override les paramètres d’Elementary.

Solution : vérifiez s’il existe des configs +materialized: view qui pourraient s’appliquer au schéma Elementary. Exécutez dbt run --select elementary --full-refresh après correction.

Erreurs de permissions Databricks sur clusters partagés

Le CLI échoue avec des erreurs de permissions sur un cluster partagé.

Solution : utilisez un cluster mono-utilisateur, ou ajoutez --update-dbt-package false à vos commandes CLI.

Et ensuite

Elementary est installé : vous disposez désormais des fondations pour une observabilité native dbt. Les tables de métadonnées se remplissent et vous pouvez générer des rapports montrant les résultats de tests et les performances des modèles.

La vraie valeur vient de ce que vous construisez par-dessus :

Des tests de détection d’anomalies qui repèrent les chutes de volume, les problèmes de fraîcheur et les dérives de distribution sans seuils manuels
Des alertes vers Slack ou Teams quand les tests échouent
Des dashboards personnalisés construits en interrogeant directement les tables Elementary depuis votre outil BI

L’approche d’Elementary (tout stocker dans votre warehouse sous forme de modèles dbt) signifie que vous n’êtes pas enfermé. Les données vous appartiennent : vous pouvez les interroger, les visualiser et les enrichir comme bon vous semble.

Consultez la documentation Elementary pour la configuration de la détection d’anomalies et la mise en place des alertes. Si vous évaluez les outils d’observabilité de manière plus large, le choix se résume souvent à ceci : préférez-vous une solution native dbt que vous configurez en YAML, ou une plateforme autonome avec une détection automatisée par ML ?