Types de métriques Lightdash et syntaxe de définition

Les métriques Lightdash se placent sous le bloc meta: dans votre YAML dbt, ce qui signifie qu’elles vivent dans le même fichier que la documentation de votre modèle, sous contrôle de version, revues dans les pull requests. La syntaxe est différente de MetricFlow — Lightdash est antérieur à la spécification MetricFlow et possède son propre vocabulaire — mais le principe sous-jacent est identique : définir le calcul une seule fois, gouverné dans le code, consommé par la couche BI.

Lightdash divise les métriques en trois catégories. La distinction n’est pas cosmétique — elle détermine ce qu’une métrique peut référencer et comment elle est évaluée.

Les trois catégories

Les métriques agrégées effectuent des agrégations SQL sur des dimensions. Elles constituent la base de votre couche de métriques. Elles référencent les dimensions avec la syntaxe ${column_name} et produisent une valeur agrégée unique quand les utilisateurs interrogent.

Les métriques non-agrégées calculent des valeurs à partir d’autres métriques. Elles ne peuvent pas toucher directement les colonnes brutes. Elles référencent des métriques existantes avec ${metric_name}. Les ratios, pourcentages et calculs dérivés appartiennent à cette catégorie.

Les métriques post-calcul (expérimentales) appliquent des fonctions de fenêtre après la résolution des autres métriques. Elles comprennent percent_of_previous, percent_of_total et running_total. Elles sont utiles pour l’analyse de contribution et les vues cumulatives, mais leur statut expérimental signifie qu’elles peuvent se comporter de manière inattendue avec des combinaisons de dimensions complexes.

La règle qui piège les utilisateurs : les métriques agrégées ne peuvent référencer que des dimensions, les métriques non-agrégées ne peuvent référencer que d’autres métriques. Mélanger les deux dans une seule expression sql provoque une erreur. Ce n’est pas un bug — cela reflète une distinction réelle dans le fonctionnement des agrégations SQL. Vous ne pouvez pas calculer SUM(revenue) / total_orders dans une seule expression car total_orders est lui-même un agrégat qui doit être calculé séparément.

Types de métriques disponibles

Placement au niveau colonne vs modèle

L’endroit où une métrique est définie détermine ce qu’elle peut référencer. La règle de placement suit une logique simple : si la métrique opère sur une seule colonne, définissez-la sous cette colonne. Si elle combine plusieurs métriques, elle va sous le modèle.

models:
  - name: mrt__sales__orders
    meta:
      primary_key: order__id
      metrics:
        average_order_value:          # model-level: references two other metrics
          type: number
          sql: "${total_revenue} / NULLIF(${total_orders}, 0)"
          format: '[$€]#,##0.00'
          description: "Average revenue per order, post-discount"
    columns:
      - name: order__id
        meta:
          metrics:
            total_orders:             # column-level: aggregates this column
              type: count_distinct
              description: "Number of unique orders"
      - name: order__revenue
        meta:
          dimension:
            type: number
            hidden: true
          metrics:
            total_revenue:            # column-level: aggregates this column
              type: sum
              format: '[$€]#,##0.00'
              description: "Sum of order revenue in EUR"

total_orders et total_revenue sont des métriques agrégées. Chacune réside sous la colonne qu’elle agrège. average_order_value est une métrique non-agrégée qui divise un agrégat par un autre — elle va sous le bloc meta.metrics du modèle car elle référence des métriques, pas des colonnes.

Le pattern NULLIF(${total_orders}, 0) est standard pour toute métrique basée sur une division. Sans lui, les plages de dates vides (zéro ordres) produisent une erreur de division par zéro plutôt qu’une valeur nulle. Utilisez toujours NULLIF pour le dénominateur dans les métriques non-agrégées.

Propriétés de configuration des métriques

filters

Disponible uniquement sur les métriques agrégées. Pré-filtre les données sous-jacentes de la métrique avant l’agrégation :

columns:
  - name: order__revenue
    meta:
      metrics:
        completed_revenue:
          type: sum
          filters:
            - field: order__status
              operator: equals
              value: completed

C’est différent du filtrage dans la vue Explore. Une propriété filters au niveau métrique est permanente — completed_revenue exclut toujours les ordres non-complétés, quel que soit le filtre appliqué par l’utilisateur dans l’interface. Utilisez ceci pour les métriques dont le filtre fait partie de la définition, et non d’un choix ad-hoc de l’utilisateur.

format et compact

format utilise les mêmes patterns de style tableur que les dimensions. compact abrège les grands nombres :

metrics:
  total_revenue:
    type: sum
    format: '[$€]#,##0.00'
    compact: millions    # displays as "€1.2M" instead of "€1,234,567.89"

Options compact : thousands, millions, billions. À utiliser avec parcimonie — les nombres abrégés perdent en précision et peuvent induire en erreur dans les tableaux où les valeurs exactes importent.

show_underlying_values

Contrôle les dimensions affichées quand un utilisateur explore en détail un résultat de métrique :

metrics:
  total_revenue:
    type: sum
    show_underlying_values:
      - order__id
      - order__created_at
      - order__customer_id
      - order__status

Sans cette propriété, Lightdash affiche toutes les dimensions non masquées dans la vue de détail. Spécifier show_underlying_values restreint le détail aux champs les plus pertinents, réduisant le bruit pour les utilisateurs finaux.

groups

Affecte la métrique à une section de la barre latérale. Détaillé dans lightdash-metrics-at-scale.

Comparaison avec MetricFlow

Si vous êtes familier avec les types de métriques MetricFlow, l’approche Lightdash paraît plus simple mais moins expressive. Lightdash n’a pas de concept de modèles sémantiques, d’entités ou de mesures — vous passez directement des colonnes dbt aux métriques. Il n’y a pas de protection contre le fanout intégrée dans la définition des métriques (c’est géré au niveau des jointures), et pas de type de calcul période sur période.

La simplicité est intentionnelle. La couche de métriques Lightdash est étroitement limitée à ce qui se trouve dans le YAML de votre projet dbt. Celle de MetricFlow est plus générale — elle est conçue pour servir n’importe quel outil en aval, pas seulement un produit BI. La contrepartie : les métriques Lightdash ne fonctionnent que dans Lightdash. Les métriques MetricFlow peuvent alimenter tout outil qui parle l’API dbt Semantic Layer.

Ni l’une ni l’autre n’est objectivement meilleure. La question est de savoir si vous souhaitez des métriques vivant entièrement dans l’écosystème d’un seul outil BI (l’approche Lightdash) ou des métriques pouvant servir plusieurs consommateurs via une API agnostique aux outils (l’approche MetricFlow). Les deux qualifient comme metrics-as-code — des définitions sous contrôle de version, revues en pull request, testées en CI.

Promouvoir des métriques ad-hoc en définitions gouvernées

Lightdash supporte des métriques personnalisées créées directement dans la vue Explore — en cliquant sur une dimension et en choisissant une agrégation. Elles sont par graphique et non gouvernées globalement. Quand une métrique personnalisée s’avère utile et que les analystes commencent à la reproduire sur plusieurs graphiques, c’est le signal pour la promouvoir.

La fonctionnalité write-back (livrée début 2025) crée une pull request vers votre YAML dbt directement depuis l’interface Lightdash. Un analyste peut définir une métrique personnalisée dans Explore, la vérifier sur des données réelles, puis la promouvoir dans le contrôle de version sans écrire manuellement du YAML. La PR passe par le processus normal de revue de code. Une fois mergée, la métrique est disponible globalement et gouvernée comme n’importe quelle autre définition.

Ce flux de travail — prototyper dans l’interface, codifier dans une PR — est le chemin pratique pour les équipes souhaitant de la gouvernance sans exiger que les analystes éditent le YAML à la main.