Skip to main content

dbt Semantic Layer

Lets agents list dbt metrics and dimensions and query governed metrics through the dbt Semantic Layer APIs.

Connect it with: API key. dbt Semantic Layer's own documentation: https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql.

What agents can do​

Connect dbt Semantic Layer so the agents working your tasks can reach it. With it connected, they can:

  • List the metrics, dimensions, entities and saved queries defined in the dbt project.
  • Query governed metrics, grouped and filtered by dimensions, through the GraphQL API.
  • Compile a metric query to the SQL it runs, to explain or check a number.

Before you start​

  • A dbt platform account on the Starter, Enterprise or Enterprise+ plan with the Semantic Layer configured for an environment: Account settings > Projects > your project > Semantic Layer.
  • At least one successful job run in that environment with metrics defined in the project.
  • An Account Admin with a Developer licence to create the service token.
  • A Jaah account. Anyone can add a personal secret; an organization secret needs an Org Owner or Admin.

Connect with dbt Semantic Layer​

Jaah connects to dbt Semantic Layer with an API key, not with a sign-in button.

Connect with an API key​

Find each value first:

Then add it to Jaah:

  1. In Jaah, open Secrets, select New, and pick the dbt Semantic Layer card.
  2. Name the secret and choose who can use it.
  3. Fill in Semantic Layer URL, Environment ID, Service token.
  4. Select Save. Jaah tests the secret straight away (see Test the connection).

Jaah encrypts what you type and never shows it again — not to you, and not to an admin.

Use your own OAuth app​

Not used: Jaah connects to dbt Semantic Layer with an API key, not through an OAuth app.

Test the connection​

Select Test on the secret. Jaah calls dbt Semantic Layer's API once (POST <Semantic Layer URL>/api/graphql) with the stored values, and shows who it answered as, or which value dbt Semantic Layer refused and the status it answered. Jaah also tests automatically when you save or reconnect.

The last result and its time stay on the secret's page, so you can see whether it still works without testing again.

Who can use it​

Every secret has an owner, and the owner decides who can use it:

  • Personal — only your own tasks can use it. This is the default.
  • Organization — every task in the organization can use it. Only Org Owners and Admins can choose this.
  • Attached to a project — every task on that project can use it, whoever started the task. See Attach a secret to a project.

More on owners and access: How secrets work.

Use it in an agent session​

An agent asks for the secret with its credential_get tool, by the secret's path, when it needs it, and gets the values for that one call. The path is the owner's prefix and the secret's name:

  • org/<name> for an organization secret,
  • projects/<project>/<name> for one attached to a project,
  • me/<name> for your personal one.

A key connection hands the agent its fields: base_url, environment_id, service_token.

Tell the agent in your task description which secret to use, for example “use the dbt Semantic Layer secret org/dbt-semantic-layer”.

Manage, rotate or disconnect​

Everything is on the secret's page under Secrets:

  • Rotate a key: create a new key at the vendor first, then select Replace on the secret and paste it. Revoke the old key at dbt Semantic Layer once the test passes. Steps: Replace or delete a secret.
  • Disconnect: select Delete. The stored values are destroyed and agents lose access on their next call. To end access at dbt Semantic Layer's side too, revoke or delete the key at dbt Semantic Layer.

Limitations​

  • The Semantic Layer serves metrics from the one environment it was configured on (usually production).
  • A wrong Environment ID can still pass the Test with no warehouse named in the result; check it reads Connected to dbt Semantic Layer on your warehouse.
  • Accounts that restrict API access by IP address must allow Jaah's outbound addresses.
  • Agents can do only what the connected dbt Semantic Layer account allows.

Troubleshooting​

Test says dbt Semantic Layer rejected the service token (401)

The token is wrong or was revoked, or the Semantic Layer URL is for another region. Pick the URL for your region and create a new service token in Account settings > Service tokens.

Test says dbt Semantic Layer rejected the service token (403)

The token lacks the Semantic Layer Only permission set on this project, or your account's IP restrictions block Jaah (account_access_denied). Edit the service token's permission sets, or allow Jaah's addresses in Account settings > IP restrictions.

Agents' metric queries fail with environment not configured

The Semantic Layer is not set up for that Environment ID. Configure it in Account settings > Projects > your project > Semantic Layer, and use that environment's ID.

Still stuck? Select Test and read the result: it names the value dbt Semantic Layer refused and the status it answered.

FAQ​

Do I need dbt Core or the dbt platform?

The Semantic Layer APIs are part of the dbt platform (dbt Cloud). A dbt Core project alone has no hosted Semantic Layer to connect to.

Can Jaah or an admin see the key or token?

No. Jaah stores it encrypted and never shows it again. Only the tasks allowed to use the secret receive it, at the moment they ask for it.

Can I connect more than one dbt Semantic Layer account?

Yes. Add one secret per account, each with its own name, and tell the agent which one to use.