The best workflow depends on where you want MetricFlow to run: use dbt platform’s hosted workflow for remotely managed commands and pull-request CI, or install MetricFlow and run its local validation commands in your Git-provider CI. In either case, keep semantic definitions in Git, review changes through pull requests, and verify that your dbt runtime supports the YAML specification you use.
What you are version-controlling
The dbt Semantic Layer centralizes metric definitions in a dbt project so downstream tools and applications can use consistent metrics. It is powered by MetricFlow, which handles metric specifications and constructs SQL queries. dbt’s Semantic Layer overview says querying through the universal Semantic Layer requires an eligible Starter, Enterprise, or Enterprise+ account. Single-tenant accounts may require setup and enablement from an account representative, so confirm eligibility for your account before planning around hosted querying.
Semantic models form the foundation of MetricFlow’s semantic graph. In dbt v1.12 and later, semantic configuration is defined in YAML associated with dbt models. The semantic models documentation describes the model layer; the supported YAML specification also depends on the dbt environment, discussed below.
Hosted dbt platform or local MetricFlow?
| Workflow | Where commands run | Version management | Pull-request validation |
|---|---|---|---|
| dbt platform | Hosted MetricFlow commands run remotely through dbt platform with the dbt sl prefix. |
dbt platform manages the hosted MetricFlow version. | dbt platform CI can test changed models, semantic models, metrics, and saved queries in a temporary schema associated with a pull request. |
| Local or self-hosted MetricFlow | MetricFlow runs in your environment using commands with the mf prefix. Git-provider CI can install it and run validations. |
Your team manages the installed engine and its compatibility with the project. | Add the required MetricFlow validation commands to your Git-provider workflow; run at least dbt parse after metric changes to refresh semantic artifacts. |
These workflows are alternatives for execution and validation, not interchangeable command sets. Check the MetricFlow commands guide for current setup and compatibility before copying commands into CI.
Recommended Free Tools
#1 Best Overall
Choose hosted dbt platform when
- Your team wants MetricFlow commands and version management handled by dbt platform.
- You want platform CI to test changed semantic content and saved queries in a pull-request-specific temporary schema.
- Your project is already connected to a supported Git provider and your organization’s plan enables the CI behavior you need.
Choose local MetricFlow when
- You do not use dbt platform or need to run validations in an environment your team controls.
- Your team is prepared to install and manage the MetricFlow engine in its CI environment.
- You want to add semantic checks to an existing Git-provider pipeline; the documented installation approach includes
python -m pip install metricflow.
Check Git-provider and plan support
dbt’s continuous integration documentation lists native integrations for GitHub and GitLab, with automated CI available on all dbt plans. Azure DevOps is also listed, but automated CI has restrictions for Starter and Developer organizations. Confirm the current plan matrix for your provider before making pull-request checks a team requirement; provider integration and automated CI availability are not the same promise.
When a platform CI job runs, it builds and tests changed models, semantic models, metrics, and saved queries in a temporary schema. The documentation says the schema is deleted when a pull request closes or merges. Customized schema naming can interfere with automatic cleanup, so review that behavior before changing the naming configuration.
Rank #2
Make semantic changes part of an ordinary Git workflow
- Connect the project to Git and branch for changes. Use feature branches and require pull-request review before merging. Keep development and production targets separate; see dbt’s version control basics.
- Make the change in the branch. Edit model and semantic YAML together where appropriate, so reviewers can see the definition alongside the data model it describes.
- Run the matching validation. For hosted MetricFlow, use the
dbt slcommand family and configured platform CI. For local MetricFlow, use themfcommand family in your managed environment. After metric changes, run at leastdbt parseto refresh the semantic artifacts. - Test outside production. Configure CI to use a sandbox or temporary schema, and use modified-only testing where it fits the change, rather than rebuilding every model for a small edit. dbt’s workflow best practices cover development and deployment practices.
- Review CI results, then merge. Resolve failures in the branch and have reviewers approve the YAML and model changes before merging into the production-bound branch.
For platform CI, remember that temporary-schema cleanup depends on the configured schema naming. For either setup, CI should validate the same runtime and YAML specification the project actually uses.
Confirm YAML compatibility before migrating
The latest YAML specification documentation lists dbt platform v1 Latest release track, dbt v2, and dbt v1.12 as supported environments. A configuration that works in one runtime should not be assumed compatible with another. Check the latest metrics YAML specification against your runtime before adopting or rewriting semantic configuration.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #3
For legacy metrics YAML, dbt documents dbt-autofix as a way to rewrite configuration to the latest spec. Treat its output as a code change: inspect the generated diff, run the project’s validations, and review it in version control rather than applying an unreviewed migration.
Choose a repository layout reviewers can navigate
There is no single required layout. Co-locating semantic YAML with the relevant marts model files keeps related definitions together. A dedicated models/semantic_models/ directory makes semantic files easier to locate and can make migration work more visible. Choose based on how your team reviews and maintains models; the semantic structure guide describes these approaches, but notes that its instructions have not yet been updated for the latest specification.
Keep generated output out of normal source control where applicable. The version control guidance identifies dbt_packages/, logs/, and target/ as directories to cover in .gitignore; older or existing projects may need these entries added manually.
Quick Recap
Practical choice
- Use hosted platform workflow if remote
dbt slcommands, platform-managed MetricFlow versions, and temporary-schema pull-request CI fit your account and provider setup. - Use local MetricFlow if your team needs locally managed execution and can own the engine installation, command compatibility, and CI setup.
- In both cases, commit semantic YAML with the project, validate changes in a non-production environment, and confirm runtime/spec and Git-provider plan compatibility before rollout.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
