Comment Lightdash se connecte à votre projet dbt

Lightdash lit la sortie compilée d’un projet dbt et génère des requêtes SQL qui s’exécutent directement sur le warehouse. Il n’importe pas de données et ne maintient pas sa propre logique de transformation. Le projet dbt fonctionne comme la couche sémantique ; la couche BI se génère elle-même à partir de lui.

Le mécanisme de connexion détermine la rapidité de propagation des modifications, le degré d’intervention manuelle requis et l’endroit où la compilation se produit.

Les trois mécanismes de connexion

Intégration de dépôt Git

Le chemin le plus simple pour les équipes utilisant déjà un hébergeur Git distant. Lightdash se connecte directement à GitHub, GitLab, Azure DevOps ou Bitbucket en utilisant une authentification OAuth ou token standard.

Quand une connexion est établie :

Lightdash lit le dépôt à la branche configurée
Compile le projet dbt côté serveur
Génère l’UI Explore à partir de la sortie compilée

La compilation se produit dans l’environnement de Lightdash, ce qui signifie que Lightdash a besoin d’accéder à vos packages dbt et à toutes les dépendances que votre projet importe via dbt deps. Pour la plupart des projets, cela fonctionne proprement. Pour les projets avec des dépendances de packages privées, vous devez configurer l’authentification séparément.

Les modifications effectuées dans le dépôt ne se propagent pas automatiquement — vous déclenchez un rafraîchissement manuellement depuis l’UI Lightdash, ou combinez ce mécanisme avec l’approche CI/CD ci-dessous.

Déploiement CLI

La commande lightdash deploy pousse un projet dbt compilé depuis une machine locale ou un runner CI/CD :

# Installer le CLI
npm install -g @lightdash/cli

# S'authentifier
lightdash login --token <votre-api-token>

# Déployer depuis le répertoire de votre projet dbt
dbt compile && lightdash deploy --project-uuid <uuid>

Le détail clé : vous exécutez dbt compile localement d’abord, puis transmettez la sortie compilée à lightdash deploy. Cela signifie que la compilation se produit dans votre environnement plutôt que dans celui de Lightdash. Si votre projet dbt a des dépendances de macros complexes, des packages privés ou une gestion de variables spécifique à l’environnement, le déploiement CLI produit souvent des résultats plus prévisibles que l’intégration Git.

Le déploiement CLI est aussi le pattern utilisé depuis les pipelines CI/CD — la distinction entre déploiement « CLI » et « CI/CD » relève davantage du contexte que du mécanisme.

Déploiement continu via CI/CD (recommandé)

L’approche de niveau production. Un workflow GitHub Actions (ou équivalent) s’exécute automatiquement après chaque fusion réussie vers la branche principale. Pas d’étapes de rafraîchissement manuel, aucune possibilité que la couche BI soit désynchronisée avec le projet dbt.

Un workflow GitHub Actions minimal :

name: Deploy to Lightdash
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dbt
        run: pip install dbt-bigquery  # ou votre adaptateur warehouse

      - name: Install Lightdash CLI
        run: npm install -g @lightdash/cli

      - name: Compile dbt project
        run: dbt compile
        env:
          DBT_PROFILES_DIR: .
          DBT_TARGET: prod

      - name: Deploy to Lightdash
        run: lightdash deploy --project-uuid ${{ secrets.LIGHTDASH_PROJECT_UUID }}
        env:
          LIGHTDASH_API_KEY: ${{ secrets.LIGHTDASH_API_KEY }}
          LIGHTDASH_URL: ${{ secrets.LIGHTDASH_URL }}

Le pattern CI/CD signifie que fusionner une pull request mettant à jour le YAML d’un modèle — ajout d’une métrique, mise à jour d’une description, ajustement d’un type de dimension — se propage automatiquement à Lightdash dans les minutes suivant la fusion. Le processus de pull request devient le workflow de gouvernance à la fois pour les modèles dbt et les définitions de la couche BI.

Ce que Lightdash lit à partir du YAML dbt

La sortie de compilation que Lightdash traite contient toutes les informations dont il a besoin pour construire l’interface Explore. Trois sources pilotent ce qui apparaît :

Les colonnes du modèle deviennent automatiquement des dimensions. Chaque colonne déclarée dans le fichier YAML d’un modèle est une dimension potentielle. Aucune annotation n’est requise. La description de la colonne depuis dbt s’affiche comme texte au survol dans la vue Explore.

Le bloc meta: est là où vit la configuration spécifique à Lightdash. Sur dbt v1.9 et antérieur, meta: est directement sous la colonne ou le modèle. Sur v1.10+ avec le moteur Fusion, il s’enveloppe dans un bloc config:.

Les descriptions dbt deviennent la couche de documentation que les utilisateurs finaux voient. C’est le mécanisme par lequel les efforts de documentation dans dbt se manifestent dans la couche BI sans aucune duplication. Écrivez les descriptions une fois, dans le contrôle de version, et elles apparaissent partout où les données sont consommées.

Un exemple minimal montrant les trois éléments :

models:
  - name: mrt__sales__orders
    description: "Une ligne par commande. Exclut les comptes de test et les commandes internes."
    meta:
      primary_key: order__id
      joins:
        - join: mrt__sales__customers
          sql_on: ${mrt__sales__orders.order__customer_id} = ${mrt__sales__customers.customer__id}
          relationship: many-to-one
      metrics:
        order__average_revenue:
          type: number
          sql: ${order__total_revenue} / NULLIF(${order__orders}, 0)
          format: '[$€]#,##0.00'
    columns:
      - name: order__id
        description: "Identifiant unique de commande"
        meta:
          metrics:
            order__orders:
              type: count_distinct
      - name: order__revenue
        description: "Total de la commande en EUR, après remises"
        meta:
          dimension:
            type: number
            hidden: true  # disponible pour les métriques, invisible comme dimension brute
          metrics:
            order__total_revenue:
              type: sum
              format: '[$€]#,##0.00'

Quand un utilisateur sélectionne des dimensions, des métriques et des filtres dans l’UI Explore, Lightdash génère du SQL optimisé avec les JOINs, GROUP BYs et clauses de filtre appropriés. La requête s’exécute directement sur le warehouse connecté. Lightdash ne met pas en cache ou ne stocke pas les résultats de requêtes (la mise en cache est une fonctionnalité Cloud Pro).

Warehouses supportés

Lightdash supporte : BigQuery, Snowflake (authentification OAuth, par mot de passe ou par clé privée), Redshift, Databricks, PostgreSQL, Trino et ClickHouse.

La connexion au warehouse est configurée séparément de la connexion au projet dbt. Lightdash a besoin d’un accès direct aux requêtes du warehouse pour exécuter le SQL qu’il génère. Il ne route pas les requêtes via dbt — dbt est uniquement utilisé au moment de la compilation pour générer le schéma que Lightdash lit.

Le bloc meta comme point d’extension

Le bloc meta: est toute la surface de configuration YAML de Lightdash. Tout ce qui rend un Explore Lightdash plus utile qu’une vue de table brute vit là : métriques, jointures, labels de groupe, formatage d’affichage, types de dimension, flags hidden et contrôles d’accès.

La contrainte délibérée est que meta: est dans les mêmes fichiers où vous documentez déjà vos modèles dbt. Il n’y a pas de fichier de configuration Lightdash séparé à maintenir en parallèle de votre schema.yml. La configuration de la couche BI est au même endroit que la documentation du modèle, revue dans les mêmes pull requests, gouvernée par la même équipe.

C’est ce qui distingue l’approche de Lightdash des outils qui maintiennent des couches de modélisation parallèles. Pour plus de détails sur la syntaxe de configuration spécifique, voir Dimensions Lightdash en YAML pour la configuration des dimensions et Types de métriques Lightdash pour les patterns de définition de métriques. Pour la question plus large de pourquoi dbt devient le fondement que les outils BI lisent, voir Centralité de dbt dans la BI.