Dépannage de l'installation d'Elementary

Elementary présente quelques modes d’échec qui se répètent systématiquement lors des installations. La plupart sont silencieux — pas de messages d’erreur, juste des données manquantes ou un rapport qui semble correct mais n’affiche rien. Cette note couvre chacun d’eux avec une démarche de diagnostic et une solution.

Rapport vide ou aucun résultat de test

Le problème le plus courant. Vous avez installé le package, exécuté dbt test, généré un rapport avec edr report, et la section des résultats de tests est vide.

Commencez par vérifier la table directement :

SELECT COUNT(*) FROM your_schema_elementary.elementary_test_results

Si cette requête renvoie zéro après l’exécution de dbt test, le package ne capture pas les résultats. Sur dbt 1.8+, cela signifie presque toujours que la macro de remplacement de matérialisation est manquante dans votre projet. Consultez Elementary dbt Materialization Override pour l’explication complète.

Si vous utilisez une version antérieure de dbt, vérifiez si les hooks on-run-end se déclenchent. Vous pouvez le confirmer en examinant la table dbt_run_results à la place :

SELECT COUNT(*) FROM your_schema_elementary.dbt_run_results

Si dbt_run_results contient des données mais que elementary_test_results est vide, quelque chose bloque spécifiquement la capture des résultats de tests. La cause la plus fréquente est un conflit de matérialisations (voir ci-dessous).

La séquence de correction après avoir résolu la cause principale :

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

Le --full-refresh recrée les tables Elementary proprement.

« command not found: edr »

L’interface CLI Elementary n’est pas dans votre PATH. Cela se produit lorsque vous installez elementary-data dans un environnement virtuel mais exécutez edr dans un shell où cet environnement n’est pas activé.

Deux solutions :

Installez dans un environnement virtuel et activez-le :

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

Ou exécutez via Python sans modification du PATH :

python -m edr report

La deuxième option fonctionne quel que soit l’environnement dans lequel le package est installé, tant que vous l’exécutez depuis le bon interpréteur Python.

Erreurs de localisation BigQuery

Erreurs mentionnant la localisation, la région ou la multi-région lors de l’exécution de edr report ou edr monitor.

L’interface CLI Elementary requiert que location soit spécifiée explicitement dans ~/.edr/profiles.yml. dbt déduit la localisation à partir du dataset existant, mais Elementary ne le fait pas. Ajoutez le paramètre :

elementary:
  outputs:
    default:
      type: bigquery
      method: oauth
      project: your-project-id
      dataset: your_schema_elementary
      location: US  # ou EU, ou une région spécifique comme europe-west1
      threads: 4

Si vous avez copié votre profil dbt comme point de départ, ce champ est probablement celui qui manque.

Tables Elementary créées en tant que vues

Les tables Elementary apparaissent dans votre entrepôt sous forme de vues plutôt que de tables incrémentales. Le rapport se charge lentement ou pas du tout, car les vues ne contiennent pas de données et chaque requête recalcule depuis le début.

Elementary configure ses propres tables avec des matérialisations incrémentales. Si elles apparaissent en tant que vues, une configuration de matérialisation dans votre dbt_project.yml remplace les paramètres d’Elementary. Recherchez quelque chose comme ceci :

models:
  your_project:
    +materialized: view  # Ceci s'applique à tout, y compris Elementary

Ou un remplacement au niveau du schéma qui capture le schéma elementary :

models:
  your_project:
    +schema: view  # Capture accidentellement le schéma elementary si configuré ainsi

Corrigez la configuration pour exclure le schéma Elementary, puis recréez les tables :

dbt run --select elementary --full-refresh

Erreurs de permissions Databricks sur les clusters partagés

L’exécution de edr contre un cluster partagé Databricks produit des erreurs de permissions. L’interface CLI tente d’écrire dans les répertoires du package lors de l’initialisation, et les permissions du cluster partagé bloquent cette opération.

Deux options :

Passez à un cluster mono-utilisateur pour les opérations Elementary. Les clusters mono-utilisateurs n’ont pas les mêmes restrictions d’écriture.

Ou ajoutez --update-dbt-package false pour ignorer l’écriture du package :

edr report --update-dbt-package false
edr monitor --update-dbt-package false --slack-token $SLACK_TOKEN --slack-channel-name data-alerts

Le flag --update-dbt-package false est sans danger en production. Il ignore simplement l’étape qui re-télécharge le package dbt Elementary avant de générer le rapport.

Vérification du bon fonctionnement

Après avoir résolu les problèmes éventuels, vérifiez que la chaîne complète fonctionne :

1. elementary_test_results contient des lignes après dbt test
2. dbt_run_results contient des lignes après dbt run
3. edr report génère un fichier HTML avec les données de test visibles
4. Le rapport affiche le nombre attendu de tests et leur statut succès/échec

Si l’étape 3 produit un rapport mais que les données semblent incorrectes (plage de dates erronée, tests manquants), vérifiez les flags que vous passez à edr report. --days-back 7 limite le rapport aux 7 derniers jours ; si vos tests n’ont été exécutés qu’une seule fois il y a plusieurs semaines, augmentez cette valeur ou omettez entièrement le flag.

Pour le contexte supplémentaire sur la configuration du profil, Elementary CLI Profile Configuration couvre la configuration complète du profil pour chaque entrepôt.