How to set up the dbt Semantic Layer in dbt Cloud

Writing semantic models and metrics is half the job. For BI tools and the APIs to query them, dbt Cloud (now called dbt platform) has to know which environment serves the Semantic Layer, which warehouse credential runs its queries, and which token each client uses. The setup takes about fifteen minutes once the metrics are merged.

Copy and paste

The checklist, in order:

1. Merge the semantic models, metrics and the time spine to the branch your production environment uses.
2. Deploy job in the production (deployment) environment that runs at least dbt parse. On dbt v2, add dbt docs generate. If the models aren’t built by another job, use dbt build. Run it once and check that it succeeds.
3. Account settings → Projects → your project → Semantic Layer → Configure Semantic Layer, and select the deployment environment.
4. Add Semantic Layer credential: a warehouse user with read access to the schemas of your marts.
5. Map a service token to the credential, with the permission sets Semantic Layer Only and Metadata Only. Copy the token: it is shown once.
6. Copy the connection details from the project page: the environment ID, the host (JDBC URL or GraphQL host) and the token. These go into Tableau, Google Sheets or your API client.

Why a deploy job

The Semantic Layer doesn’t read your branch. It reads the semantic_manifest.json produced by the last successful run in the environment you selected, and queries the tables that environment built. Two consequences:

• A new metric becomes queryable only after it is merged and a job in that environment has run. Add the parse step to the job that already builds production, so every deployment refreshes the definitions.
• Without any successful run, queries fail; see how to fix dbt sl query failing because there is no successful production job.

The documentation lists querying against development environments as coming soon: today, the Semantic Layer serves deployment environments.

Credentials and tokens

The credential is the warehouse login the Semantic Layer uses for every query, so warehouse permissions apply to it, not to the person asking. Give it read-only access to the schemas your semantic models use.

• Service tokens are linked to that credential and meant for shared connections, such as a published Tableau workbook. A Starter plan allows one credential per project with any number of tokens; Enterprise plans can add several credentials, for example one per team, each with its own tokens.
• Personal access tokens run queries with the user’s own development credentials, which suits analysts connecting from their own tools.
• SSO is supported for user accounts but not for the production credential.

Who can do it

You need to be an account Owner (or, on Enterprise plans, have Account Admin or a comparable permission set) with a Developer licence. A free trial of the Starter plan includes the Semantic Layer.

Check it works

From the dbt Cloud CLI or the Studio IDE:

dbt sl list metrics
dbt sl query --metrics revenue --group-by metric_time__month --limit 3

The CLI needs a dbt_cloud.yml pointing at the project; see how to install and configure the dbt Cloud CLI and how to find your environment-id. Then connect a tool: Google Sheets is the quickest test.

Based on the dbt platform documentation (October 2026).