Configuration des dimensions Lightdash dans le YAML dbt

Chaque colonne déclarée dans le YAML d’un modèle dbt devient automatiquement une dimension dans Lightdash. Il n’y a pas d’étape d’import séparée, pas de table de correspondance, pas d’ETL entre votre projet dbt et votre couche BI. Lightdash lit votre dépôt, compile le projet, et la vue Explore se peuple. Ce couplage étroit est l’intérêt même de construire un outil BI par-dessus dbt — votre couche de transformation et votre couche analytique partagent une seule source de vérité.

Le bloc meta: sous chaque colonne est l’endroit où vous configurez la manière dont Lightdash présente cette dimension. Sur dbt v1.9 et antérieur, meta: se trouve directement sous la colonne. Sur v1.10+ (et Fusion), il s’imbrique dans un bloc config:. Les exemples ici utilisent la syntaxe v1.9, qui reste la norme dans les projets en production.

Types de dimensions

Lightdash supporte cinq types : string, number, date, timestamp et boolean. Les types sont détectés automatiquement depuis le schéma de votre entrepôt, mais peuvent être surchargés dans le YAML si l’inférence est incorrecte ou si vous souhaitez contrôler la présentation d’une colonne :

models:
  - name: mrt__sales__orders
    columns:
      - name: order__created_at
        description: "Timestamp when the order was placed"
        meta:
          dimension:
            type: timestamp
      - name: order__status
        description: "Current order status"
        meta:
          dimension:
            type: string
      - name: order__revenue
        description: "Order total in EUR, after discounts"
        meta:
          dimension:
            type: number

Le type a son importance car il contrôle les opérations que Lightdash propose dans l’interface. Les dimensions numériques disposent d’options d’agrégat (sum, average, count). Les dimensions timestamp offrent des sélecteurs de granularité temporelle. Les dimensions string bénéficient d’opérateurs de filtre tels que “contains” et “starts with”.

Propriétés clés

label

Surcharge le nom d’affichage. La valeur par défaut est une version humanisée du nom de colonne (order__revenue devient “Order Revenue”). Utilisez label quand la valeur humanisée par défaut est incorrecte, maladroite ou manque de contexte important :

meta:
  dimension:
    type: number
    label: "Revenue (EUR, post-discount)"

Les labels n’affectent que ce que voient les utilisateurs dans la vue Explore. Le nom de colonne reste l’identifiant dans les références YAML.

description

S’affiche au survol dans la vue Explore et hérite de la description de la colonne dbt si aucune description au niveau dimension n’est définie. C’est le mécanisme par lequel votre documentation dbt remonte dans la couche BI sans duplication. Rédigez la description au niveau colonne, pas dans meta.dimension, et Lightdash la récupère automatiquement.

format

Accepte des patterns de formatage de nombres au style tableur :

meta:
  dimension:
    type: number
    format: '[$€]#,##0.00'   # €1,234.56

Patterns courants :

• '[$€]#,##0.00' — euro avec deux décimales
• '$#,##0' — dollar, sans centimes
• '0.0%' — pourcentage avec une décimale
• '#,##0.0K' — milliers abrégés

Le format s’applique dans la vue Explore et dans les labels d’axe des graphiques. Il n’affecte pas les données sous-jacentes — la valeur brute reste toujours accessible pour les calculs de métriques.

hidden

Le flag hidden: true exclut une dimension de la barre latérale Explore tout en la maintenant disponible pour les calculs de métriques. C’est le pattern standard pour les colonnes de revenus bruts que vous souhaitez agréger sans exposer directement :

- name: order__revenue
  meta:
    dimension:
      type: number
      format: '[$€]#,##0.00'
      hidden: true  # available for metrics, invisible to users
    metrics:
      total_revenue:
        type: sum
        format: '[$€]#,##0.00'

Les utilisateurs voient total_revenue dans la barre latérale. Ils ne voient pas order__revenue comme dimension indépendante. Cela évite la confusion d’avoir à la fois une colonne brute et son agrégat visibles simultanément.

time_intervals

Contrôle les granularités disponibles pour les champs date et timestamp. L’ensemble par défaut est adapté à la plupart des cas d’usage, mais vous pouvez le personnaliser :

meta:
  dimension:
    type: timestamp
    time_intervals: ['DAY', 'WEEK', 'MONTH', 'QUARTER', 'YEAR']

Définissez time_intervals: 'OFF' pour désactiver complètement l’expansion automatique des dimensions temporelles. Utile pour les champs date représentant des catégories (codes de période fiscale, dates de cohorte) plutôt que des séries temporelles.

groups

Affecte la dimension à une section nommée dans la barre latérale. Les groupes se replient et se déplient — c’est la solution pratique pour une barre latérale avec plus de 30 champs. Détaillé dans lightdash-metrics-at-scale.

Additional Dimensions

Certaines valeurs calculées ne correspondent pas à des colonnes physiques. additional_dimensions sous le bloc meta: du modèle les gère :

models:
  - name: mrt__sales__orders
    meta:
      additional_dimensions:
        order__revenue_thousands:
          type: number
          sql: "${TABLE}.order__revenue / 1000"
          format: '[$€]#,##0.0K'
          label: "Revenue (thousands)"
        is_high_value:
          type: boolean
          sql: "${TABLE}.order__revenue > 500"
          label: "High-Value Order"

Le champ sql utilise ${TABLE} comme référence à la table sous-jacente du modèle. Vous pouvez également référencer d’autres dimensions avec ${dimension_name}.

additional_dimensions est utile pour :

• Les conversions d’unités (revenus dans différentes devises, temps dans différentes unités)
• Les catégorisations dérivées qui ne nécessitent pas leur propre colonne SQL
• Les flags booléens calculés à partir de seuils
• Les transformations adaptées à l’affichage que vous ne souhaitez pas matérialiser dans dbt

La contrepartie est que ces dimensions vivent dans le YAML plutôt que dans le SQL, ce qui signifie qu’elles ne peuvent pas être indexées ou optimisées par l’entrepôt. Pour des calculs intensifs ou des colonnes dérivées fréquemment filtrées, les matérialiser dans un modèle dbt intermédiaire est le meilleur choix.

Du flux colonne à dimension

Chaque colonne dans le YAML de votre modèle dbt est une dimension potentielle. Le bloc meta.dimension est optionnel — si vous l’omettez, Lightdash crée quand même une dimension à partir de la colonne avec un type détecté automatiquement. Le bloc meta.dimension est l’endroit où vous surchargez les valeurs par défaut, ajoutez du formatage, masquez les colonnes brutes et contrôlez les granularités temporelles.

La description de la colonne dans dbt transite automatiquement. La documentation rédigée au niveau colonne remonte dans Lightdash sans duplication.

Pour savoir comment définir les métriques qui reposent sur ces dimensions, voir lightdash-metric-types.