Installation et configuration de MetricFlow

MetricFlow est le moteur de génération SQL derrière la couche sémantique dbt. Dans dbt Core, c’est un package Python séparé à installer aux côtés de l’adapteur. Dans dbt Cloud, il est intégré.

Installation dbt Core

Installez le bundle MetricFlow qui correspond à la plateforme de données. Le nom du package suit le pattern dbt-metricflow[adapter] :

# Snowflake
pip install "dbt-metricflow[dbt-snowflake]"

# BigQuery
pip install "dbt-metricflow[dbt-bigquery]"

# Databricks
pip install "dbt-metricflow[dbt-databricks]"

# Redshift
pip install "dbt-metricflow[dbt-redshift]"

# Postgres
pip install "dbt-metricflow[dbt-postgres]"

Les crochets spécifient l’adapteur comme dépendance optionnelle. Installer dbt-metricflow sans adapteur ne permettrait pas d’exécuter des requêtes contre l’entrepôt.

MetricFlow supporte Snowflake, BigQuery, Databricks, Redshift, Postgres (Core uniquement) et Trino. Si l’adapteur n’est pas dans cette liste, MetricFlow ne peut pas générer de SQL pour lui — il faudrait dbt Cloud, qui a sa propre matrice de support de plateformes.

Épinglez la version dans le fichier requirements.txt aux côtés de la version de l’adapteur :

dbt-metricflow[dbt-snowflake]==1.x.x

Le package MetricFlow intègre une version compatible de l’adapteur. En cas de conflits de version d’adapteur dans l’environnement, installer dbt-metricflow en premier et le laisser résoudre la version de l’adapteur est généralement plus propre que d’essayer d’épingler les deux indépendamment.

dbt Cloud

Aucune installation nécessaire. MetricFlow fait partie du runtime dbt Cloud. La commande CLI est dbt sl au lieu de mf :

# Core
mf validate-configs
mf query --metrics revenue --group-by metric_time

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

La syntaxe YAML des modèles sémantiques et métriques est identique entre Core et Cloud. La différence est dans ce qui se passe après la définition des métriques — Cloud ajoute un accès JDBC, GraphQL et REST API qui permet aux outils BI d’interroger directement la couche sémantique. Core reste limité aux requêtes CLI.

Voir Cadre de décision dbt Core vs Cloud pour une comparaison complète de ce qui est disponible dans chaque version.

Structure de projet requise

Deux éléments doivent être en place avant de définir des modèles sémantiques.

Premièrement, MetricFlow doit savoir où se trouvent les fichiers de modèles sémantiques. Dans dbt_project.yml, configurez le bloc semantic-layer :

semantic-layer:
  time_spine:
    standard_granularity_column: date_day

Deuxièmement, créez le modèle de timespine. Les métriques cumulatives et le remplissage des lacunes dans les séries temporelles nécessitent toutes les deux une table de dates continue. Sans elle, les requêtes impliquant ces fonctionnalités échoueront. La créer tôt évite la confusion plus tard quand une métrique cumulative génère une erreur sans message évident sur la raison.

La configuration minimale viable est :

Installer le package
Ajouter la config semantic-layer à dbt_project.yml
Créer metricflow_time_spine.sql
Exécuter dbt build -s metricflow_time_spine

Après cela, mf validate-configs devrait passer (en supposant que les YAML de modèles sémantiques se parsent correctement), et mf query devrait fonctionner.

Vérifier l’installation

Exécutez la validation immédiatement après la configuration :

mf validate-configs

Si cela retourne une erreur sur des artefacts ou manifestes manquants, exécutez d’abord dbt parse :

dbt parse && mf validate-configs

La commande dbt parse génère target/semantic_manifest.json, dont MetricFlow a besoin pour comprendre les modèles sémantiques et métriques du projet. Il faudra exécuter dbt parse à chaque modification des définitions YAML pour que MetricFlow prenne en compte les changements.

Une sortie de validation réussie ressemble à quelque chose comme :

Validating semantic model orders...
Validating metric revenue...
Validating metric orders...
All validations passed.

Sans modèles sémantiques ni métriques définis, la validation ne retournera rien à valider — c’est normal. L’absence d’erreurs signifie que l’installation fonctionne. Ajoutez le premier modèle sémantique et la première métrique, ré-exécutez la validation et vous les verrez validés.