Use dbt Sync to bring your semantic layer definitions into GrowthBook. The new @growthbook/dbt CLI turns dbt semantic models into GrowthBook fact tables and dbt metrics into fact metrics. Each run of the CLI updates them.
How the sync works
The CLI reads target/manifest.json, which dbt writes after dbt parse. It needs no warehouse connection and no dbt runtime of its own. It uses the same bulk import API as the GitHub metrics workflow, but it reads dbt's definitions instead of a GrowthBook-format YAML file.
- Each semantic model becomes a fact table, with its agg_time_dimension as the timestamp column.
- Most simple metrics become Mean metrics, ratio metrics become Ratio metrics, and conversion metrics become two-step Funnel metrics. Median and percentile aggregations become Quantile metrics.
- Synced fact tables and fact metrics are managed by dbt and read-only in the GrowthBook UI. You change them in dbt and sync again.
- Definitions the CLI can't map, such as min aggregations, are skipped with a message.
Settings with no dbt equivalent, such as conversion windows and capping, go under config.meta.growthbook. The CLI upserts by ID, so renaming a dbt metric creates a new GrowthBook metric. Run with --prune to archive the old one.
Check with a dry run, then automate
Start with --dry-run. It validates the sync against the GrowthBook API without writing anything and lists what it would skip. This excerpt from the docs assumes ds_abc123 is your Data Source ID and maps a dbt customer entity to user_id:
Remove --dry-run to apply the changes. If your API key requires a person to confirm writes, the CLI prints a confirmation link and waits. You can run the same command by hand or as a CI step after dbt parse. Add --strict in CI so the job exits with an error when anything is skipped.
Getting started
- Open Metrics and Data → Data Sources, open the Data Source your dbt project writes to, and copy its ID from the URL.
- Go to Settings → API Keys and create a Secret Key with the Admin role.
- Synced Quantile and Funnel metrics need a plan that includes those metric types. If you self-host, use GrowthBook 5.2 or later for this workflow.
Follow the dbt semantic layer sync guide for the full mapping, selectors, and overrides.
