Composants du modèle sémantique MetricFlow

Un modèle sémantique est une couche YAML qui décrit un modèle dbt à MetricFlow. Il a une relation un-à-un avec un modèle SQL ou Python dbt et annote ce modèle avec trois types d’informations : les entités (comment les tables se joignent), les dimensions (comment les données peuvent être découpées) et les mesures (ce qui peut être agrégé). Tout le reste dans la couche sémantique dbt se construit sur ces trois composants.

La structure complète ressemble à ceci :

semantic_models:
  - name: orders
    description: Order transactions with revenue and quantity
    model: ref('mrt__sales__orders')
    defaults:
      agg_time_dimension: order__created_at

    entities:
      - name: order_id
        type: primary
      - name: customer_id
        type: foreign
      - name: product_id
        type: foreign

    dimensions:
      - name: order__created_at
        type: time
        type_params:
          time_granularity: day
      - name: order__status
        type: categorical
      - name: order__channel
        type: categorical

    measures:
      - name: order_total
        agg: sum
        expr: order__amount
        description: Sum of order amounts
      - name: order_count
        agg: count
        expr: order_id
      - name: distinct_customers
        agg: count_distinct
        expr: customer_id

Le champ model pointe vers le modèle de la couche mart. Les modèles sémantiques doivent référencer les marts, pas les modèles de base ou intermédiaires. Les marts sont des interfaces stables ; les modèles intermédiaires sont refactorisés sans avertissement. Plus à ce sujet dans organisation des métriques dans dbt.

Entités

Les entités sont des clés de jointure. Elles indiquent à MetricFlow comment les modèles sémantiques se connectent les uns aux autres, formant le graphe sémantique qui rend les jointures automatiques possibles. On définit une entité une fois, et MetricFlow l’utilise pour naviguer entre les tables quand une requête couvre plusieurs modèles sémantiques.

Quatre types d’entités existent :

• primary — un enregistrement par ligne, pas de nulls. C’est le grain du modèle sémantique, équivalent à une clé primaire. Chaque modèle sémantique doit en avoir exactement une.
• unique — un par ligne, nulls autorisés. À utiliser quand une colonne identifie de façon unique les lignes mais peut être absente.
• foreign — de zéro à plusieurs instances. Un customer_id dans une table de commandes est étranger car plusieurs commandes partagent le même client.
• natural — colonnes qui identifient de façon unique les enregistrements basés sur des données du monde réel, comme les codes pays ou les SKUs de produits.

L’entité primary est la plus conséquente. MetricFlow l’utilise pour déterminer le grain du modèle et valider que les jointures ont du sens. Si un modèle sémantique n’a pas d’entité primaire, ou en a deux, MetricFlow le rejettera.

Quand des métriques sont interrogées depuis deux modèles sémantiques différents — par exemple, le revenu depuis orders et le nombre de clients depuis customers — MetricFlow regarde les entités pour trouver un chemin de jointure partagé. Si orders a customer_id comme entité étrangère et customers a customer_id comme entité primaire, MetricFlow sait comment les joindre. Il n’est pas nécessaire d’écrire la JOIN. Il suffit de demander les métriques.

Dimensions

Les dimensions sont les colonnes sur lesquelles on regroupe, filtre et découpe les métriques. Deux types existent : temporel et catégoriel.

Les dimensions temporelles sont requises pour toute requête basée sur le temps. Le agg_time_dimension dans le bloc defaults spécifie quelle dimension temporelle MetricFlow utilise quand metric_time est interrogé — la dimension temporelle intégrée par laquelle passent toutes les requêtes de séries temporelles.

dimensions:
  - name: order__created_at
    type: time
    type_params:
      time_granularity: day

Le paramètre time_granularity contrôle le niveau le plus fin auquel cette dimension opère. Une granularité day signifie que les requêtes peuvent regrouper par jour, semaine, mois, trimestre ou année. MetricFlow gère la troncature automatiquement au moment de la requête.

Les dimensions catégorielles sont tout le reste sur quoi on regroupe :

dimensions:
  - name: order__status
    type: categorical
  - name: order__channel
    type: categorical

La convention de nommage avec double tiret bas (order__status) vient de l’approche de MetricFlow pour la résolution des dimensions. Quand on référence une dimension dans un filtre ou un group-by, on utilise le nom d’entité et le nom de dimension ensemble : orders__order__status. Cela rend explicite de quel modèle sémantique provient la dimension, ce qui importe quand plusieurs modèles partagent des noms de dimensions.

Une dimension sans entité primaire dans son modèle sémantique n’apparaîtra pas dans les résultats de requête. Chaque dimension a besoin d’une entité primaire pour l’ancrer.

Mesures

Les mesures sont des agrégations numériques définies sur des colonnes du modèle sous-jacent. Elles sont les blocs de construction que les métriques référencent. La distinction entre mesures et métriques importe : les mesures définissent la mécanique d’agrégation, les métriques définissent le sens métier.

measures:
  - name: order_total
    agg: sum
    expr: order__amount
    description: Sum of order amounts
  - name: order_count
    agg: count
    expr: order_id
  - name: distinct_customers
    agg: count_distinct
    expr: customer_id

Le champ expr est le nom de colonne (ou une expression SQL) du modèle sous-jacent. Le champ agg est la fonction d’agrégation que MetricFlow applique.

Agrégations supportées : sum, count, count_distinct, avg, min, max, median et percentile. Les deux dernières sont moins souvent nécessaires mais utiles pour les métriques de latence et le suivi des SLAs.

Les mesures doivent rester proches des agrégations brutes. Évitez d’encoder la logique métier au niveau de la mesure — cela appartient aux filtres de métriques. Une mesure nommée order_total qui agrège order__amount est réutilisable pour enterprise_revenue, smb_revenue, mtd_revenue et toute autre métrique qui a besoin des montants totaux de commandes. Une mesure nommée enterprise_order_total avec un filtre intégré ne sert qu’un seul objectif.

Le champ defaults.agg_time_dimension au niveau du modèle sémantique définit la dimension temporelle par défaut pour toutes les mesures de ce modèle. MetricFlow l’utilise lors de la génération des requêtes de séries temporelles et a besoin de savoir par quelle colonne de date regrouper.

Comment ils se composent

Les trois composants fonctionnent ensemble pour former un graphe navigable. Les entités connectent les modèles. Les dimensions permettent le filtrage. Les mesures alimentent les métriques. Une requête comme « montrez-moi le revenu par canal pour les 30 derniers jours » se résout ainsi :

1. Trouver la métrique revenue
2. La tracer jusqu’à la mesure order_total sur le modèle sémantique orders
3. Trouver la dimension order__channel sur orders
4. Appliquer le filtre temporel via order__created_at
5. Générer le SQL : SELECT order__channel, SUM(order__amount) FROM orders WHERE order__created_at >= ...

On définit les composants une fois. MetricFlow gère la génération SQL. Quand le modèle mart change les noms de colonnes, on met à jour le YAML du modèle sémantique et chaque métrique qui en dépend se met à jour automatiquement — sans avoir à chercher dans les tableaux de bord.