Requêtes MetricFlow via la CLI

MetricFlow expose deux interfaces CLI pour interroger les métriques : mf (dbt Core) et dbt sl (dbt Cloud). Les commandes sont équivalentes dans ce qu’elles peuvent exprimer ; la syntaxe diffère légèrement entre les deux. La couche sémantique dbt Cloud ajoute également des APIs JDBC, GraphQL et REST pour les connexions d’outils BI — celles-ci ne sont pas disponibles dans Core.

Générer le manifeste sémantique

Avant qu’une requête fonctionne, MetricFlow a besoin d’un manifeste sémantique compilé. C’est un artefact qui indique à MetricFlow quels modèles sémantiques et métriques existent, dérivés de vos définitions YAML.

dbt parse

Exécutez cette commande à chaque modification de YAML de modèle sémantique ou de métrique. Si une requête est lancée après une modification YAML sans ré-analyse, MetricFlow travaillera sur le manifeste précédent et ne reflétera pas les changements.

Le manifeste réside dans target/semantic_manifest.json. Il n’est pas nécessaire de toucher ce fichier directement — MetricFlow le lit automatiquement.

Syntaxe de requête de base

La structure de requête principale est --metrics plus un --group-by optionnel :

# dbt Core
mf query --metrics revenue --group-by metric_time

# dbt Cloud
dbt sl query --metrics revenue --group-by metric_time

metric_time est une dimension intégrée disponible sur toute métrique. Elle utilise l’agg_time_dimension configuré sur le modèle sémantique sous-jacent et supporte la gestion automatique de la granularité.

Interroger plusieurs métriques à la fois fonctionne tant qu’elles partagent des modèles sémantiques compatibles (MetricFlow peut les joindre via des entités partagées) :

mf query --metrics revenue,orders --group-by metric_time,order__channel

Le résultat est une requête unique avec les deux métriques comme colonnes, découpées par temps et canal.

Références de dimensions

Les noms de dimensions dans les clauses group-by suivent le pattern semantic_model__dimension_name. Pour le modèle sémantique orders avec une dimension order__channel :

mf query --metrics revenue --group-by metric_time,order__channel

Ceci résout en regroupant la métrique de revenu par la dimension catégorielle order__channel sur le modèle sémantique orders.

On peut explorer quelles dimensions sont disponibles pour une métrique donnée :

mf list dimensions --metrics revenue

Utile quand on n’est pas sûr des dimensions compatibles avec une métrique — MetricFlow liste uniquement les dimensions accessibles via le graphe sémantique depuis le modèle sémantique de cette métrique.

Filtrer avec —where

Le flag --where applique des filtres en utilisant une syntaxe de type Jinja qui référence les dimensions via le moteur de résolution de MetricFlow. On n’écrit pas des noms de colonnes SQL bruts — on référence les dimensions par leur chemin sémantique.

mf query --metrics revenue \
  --group-by metric_time \
  --where "{{ Dimension('orders__order__channel') }} = 'web'"

La syntaxe est {{ Dimension('semantic_model__dimension_name') }}. MetricFlow résout cela à la colonne et table correctes, gérant toutes les jointures nécessaires pour atteindre la dimension.

Pour les dimensions temporelles avec une granularité spécifique :

mf query --metrics revenue \
  --group-by metric_time \
  --where "{{ TimeDimension('orders__order__created_at', 'month') }} >= '2025-01-01'"

Le second argument de TimeDimension() définit la granularité de troncature. Cela importe quand la valeur du filtre est à la limite d’une période — filtrer au grain month tronque les dates au premier du mois avant de comparer, ce qui est différent du filtrage au grain day.

Plusieurs conditions fonctionnent avec AND :

mf query --metrics revenue,orders \
  --group-by metric_time,order__status \
  --where "{{ Dimension('orders__order__channel') }} = 'web' AND {{ Dimension('orders__order__status') }} != 'cancelled'"

Contrôler la granularité temporelle

Par défaut, metric_time retourne les données à la granularité de la dimension temporelle sous-jacente (typiquement day). On peut demander une granularité plus grossière :

mf query --metrics revenue --group-by metric_time__month

Le suffixe de granularité avec double tiret bas fonctionne pour __day, __week, __month, __quarter et __year. MetricFlow tronque la dimension temporelle à la granularité demandée et agrège en conséquence.

Validation avant de requêter

Avant de requêter, validez que les définitions YAML se parsent sans erreurs :

# dbt Core
mf validate-configs

# dbt Cloud
dbt sl validate

Modes d’échec courants :

• “ensure that you’ve ran an artifacts…” — Exécutez dbt parse ou dbt build d’abord pour générer le manifeste sémantique.
• Dimensions n’apparaissant pas — Chaque dimension nécessite une entité primaire dans son modèle sémantique.
• Conflit Metafont sur macOS — La commande mf peut entrer en conflit avec le package LaTeX Metafont. Désinstallez le package LaTeX si mf produit une sortie inattendue.

Les flags --verbose-issues --show-all sur la validation affichent plus de détails lors du débogage des échecs :

mf validate-configs --verbose-issues --show-all

À quoi sert la CLI

La CLI est adaptée à l’exploration en phase de développement : vérifier qu’une nouvelle définition de métrique retourne les valeurs attendues, tester la syntaxe des filtres avant de l’encoder en YAML, et valider que les jointures fonctionnent comme prévu entre les modèles sémantiques.

Pour l’usage en production, la CLI de dbt Core est la seule interface disponible au-delà du SQL brut contre l’entrepôt. dbt Cloud ajoute les APIs JDBC et GraphQL auxquelles les outils BI se connectent — chaque outil de tableau de bord peut alors consommer les mêmes définitions de métriques gouvernées via l’API plutôt qu’écrire son propre SQL.