Configuration du profil CLI Elementary

Le CLI Elementary (edr) dispose de son propre profil de connexion, séparé du profil dbt. C’est intentionnel : le CLI s’exécute indépendamment de dbt, selon le calendrier de votre choix, et peut nécessiter des identifiants ou des permissions différents de votre compte de service dbt. Les profils se trouvent dans ~/.edr/profiles.yml plutôt que ~/.dbt/profiles.yml.

Le moyen le plus rapide d’obtenir un modèle de départ correct est d’exécuter la macro génératrice depuis votre projet dbt :

dbt run-operation elementary.generate_elementary_cli_profile

Cela produit du YAML pré-rempli pour votre type d’adaptateur. Copiez-le dans ~/.edr/profiles.yml et renseignez les valeurs réelles.

BigQuery

Un profil CLI BigQuery complet utilisant OAuth (adapté à l’usage local) :

elementary:
  outputs:
    default:
      type: bigquery
      method: oauth
      project: your-project-id
      dataset: your_schema_elementary
      location: US
      threads: 4

Pour les déploiements en production où edr s’exécute depuis un système CI/CD ou un planificateur, utilisez plutôt un compte de service :

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

Le champ location est la source d’erreurs la plus courante sur les configurations BigQuery. dbt infère automatiquement l’emplacement du dataset, donc de nombreuses équipes l’omettent dans leurs profils dbt sans jamais le remarquer. Le CLI Elementary ne l’infère pas — vous devez le fournir explicitement. Utilisez US, EU ou votre région spécifique (par ex., europe-west1). Si vous voyez des erreurs de localisation ou de région provenant de edr, c’est presque toujours la cause.

Permissions requises

Le compte de service (ou l’utilisateur) exécutant edr a besoin d’un accès en lecture aux tables Elementary et d’un accès aux métadonnées de vos datasets dbt. Il n’a pas besoin d’un accès en écriture à vos modèles. L’ensemble minimal :

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 exécuter des requêtes en lecture)

Ce sont des rôles orientés lecture. Le CLI ne modifie pas vos données de production.

Snowflake

Snowflake supporte l’authentification par mot de passe ou par paire de clés. La paire de clés est préférable pour les accès de type service :

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

Le rôle a besoin d’accès au schéma Elementary et rien d’autre. Créez un rôle minimal plutôt que de réutiliser un rôle existant avec des permissions plus larges :

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;

Le grant FUTURE TABLES garantit qu’à mesure qu’Elementary crée de nouvelles tables de métadonnées, le rôle peut les lire sans nécessiter de mises à jour des permissions.

Databricks

Pour Unity Catalog, le profil nécessite un paramètre catalog pour gérer l’espace de noms à trois niveaux (catalog.schema.table) :

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

Pour les déploiements en production, utilisez des service principals plutôt que des personal access tokens.

Un problème spécifique à Databricks : exécuter edr sur un cluster partagé peut produire des erreurs de permission. Le CLI tente d’écrire dans les répertoires du package lors de l’initialisation, et les clusters partagés restreignent cela. Le correctif consiste à utiliser un cluster à utilisateur unique, ou à passer --update-dbt-package false à toutes les commandes edr, ce qui ignore 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

Installation du CLI

Installez edr avec les extras spécifiques à l’adaptateur correspondant à votre entrepôt :

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

Les extras d’adaptateur embarquent les bonnes dépendances de pilote. Une installation sans eux entraîne des imports manquants lorsque edr tente de se connecter.

Si edr n’est pas trouvé après l’installation, vous l’exécutez probablement en dehors d’un environnement virtuel activé. Soit activez l’environnement où vous l’avez installé, soit exécutez-le directement via Python :

python -m edr report

Une fois le profil configuré et le CLI installé, edr report génère un fichier HTML dans ./edr_target/. La note Elementary Setup Troubleshooting couvre ce qu’il faut vérifier si le rapport ne montre aucune donnée.