dbt Semantic Layer
Discover and query governed dbt metrics from a Swarmz project
Connect dbt Semantic Layer when a project should use governed metrics instead of direct warehouse SQL. The connector discovers metrics and dimensions, starts an asynchronous semantic query, and reads the result through dbt's GraphQL API.
Availability
A Swarmz administrator must show dbt Semantic Layer under Platform config > Integrations and enable the data and analytics connector flag. The connector uses a dbt service token, not OAuth.
Before you connect
Create a dbt service token that starts with dbtc_ and grant only the permissions required to query the intended environment. dbt documents service tokens.
You also need the numeric environment ID and one supported Semantic Layer host:
semantic-layer.cloud.getdbt.comsemantic-layer.emea.dbt.comsemantic-layer.au.dbt.com
Swarmz rejects custom hosts. This prevents a stored connection from forwarding its authorization header to an arbitrary server.
Connect dbt Semantic Layer
- In the Swarmz project, open Settings > Integrations and select dbt Semantic Layer.
- Enter the Service token.
- Enter the Semantic Layer host for your dbt region.
- Enter the Environment ID.
- Select Save connection.
Swarmz requests the metric list before saving the connection. A token for another environment, an unsupported host, or missing Semantic Layer permission causes setup to fail.
Available operations
| Operation | What it does | Limit per minute |
|---|---|---|
list_metrics | Lists governed metrics with optional search | 30 |
get_dimensions | Lists dimensions available for selected metrics | 30 |
create_query | Starts a bounded semantic query | 10 |
get_query | Reads query status and one result page | 30 |
Creating a query requires allow-once approval because it can consume warehouse compute. A query can include up to 20 metrics, groupings, ordering fields, and filters, with a result limit up to 10,000 rows.
Ask the AI to use dbt Semantic Layer
- “Discover the governed revenue metrics and build a monthly revenue chart.”
- “Show which dimensions are available for
ordersbefore creating the query.” - “Use the dbt metric instead of writing raw warehouse SQL.”
Verify dbt Semantic Layer
- List metrics and confirm a known metric appears.
- Request dimensions for that metric.
- Start a small query with a low limit.
- Poll the returned query ID and confirm the completed records match dbt's metric definition.
To rotate the token, create a replacement in dbt, edit the Swarmz connection, and repeat the metric check before revoking the old token. Select Remove and revoke the service token to remove access.