Connecting dbt platform

Connect to a dbt platform account to see the health of the dbt models behind your content. After you connect, Omni shows a dbt data health indicator on published dashboards and apps that have an exposure entry. The indicator shows whether the upstream models built, whether their sources are fresh, and whether their tests passed. The dbt platform connection doesn’t replace the Git-based dbt integration. Omni still syncs dbt metadata from your Git repository, and you can use both on the same connection.

​

How it works

• One dbt platform account for each organization. An Organization Admin connects the account with OAuth.
• One dbt platform project for each Omni connection. A Connection Admin picks the project and the environment that Omni reads.

​

Requirements

To follow the steps in this guide, you’ll need:

• Organization Admin permissions in Omni
• A dbt platform plan that includes the Discovery API: Starter, Enterprise, or Enterprise+. See the dbt documentation for current plan requirements.
• The account access URL and the Discovery API URL for your dbt platform account.
• A dbt platform user who can access the project or projects you’d like to use. Omni inherits the permissions of the dbt platform user who connects to it.
• dbt exposures for your dashboards and apps. See push exposures from Omni.

​

Connect dbt platform

1. In Omni, navigate to Settings > Integrations and click the dbt platform tab.
2. Fill in the following fields:
   • In Account access URL, enter the access URL from Account settings > Access URLs in dbt platform. For example, https://ab123.us1.dbt.com.
   • In Discovery API URL, enter the Discovery API URL from the same page. For example, https://ab123.metadata.us1.dbt.com.
3. Click Connect dbt platform.
4. Sign in to dbt platform.
5. On the consent screen, opt into Keep session alive, then approve access.

​

Pick a dbt platform project for a connection

Once dbt platform is connected, you can pick the project and environment that Omni uses for each connection.

1. In Omni, navigate to Settings > Connections.
2. Select the connection you want to manage.
3. Click the dbt tab.
4. In the dbt platform project section, select a project from the list.
5. Click Save.
6. Select an Environment. Omni reads data health from this environment.
7. Click Save.

Each connection can have one dbt platform project. To use a different project, click Remove, then add the new project.

​

Manage the connection

The dbt platform tab shows the account name, access URL, account ID, the Omni user who connected it, and when Omni last refreshed the token. Connection Admins can see this tab. Only Organization Admins can use these actions:

• Test connection reads the account and its projects, and checks the Discovery API URL. If the test succeeds, Omni shows the account name and the number of projects it can see.
• Reconnect opens a dialog with both URLs filled in. Use it to restore an expired connection.
• Disconnect disconnects dbt platform for the whole organization. Omni keeps each connection’s project settings. If you connect the same account again, the settings come back.
  dbt platform has no way for Omni to revoke access. After you disconnect, the session in dbt platform stays until it expires.

An organization can only connect to one dbt platform account. To connect a different account, disconnect the current one first. When you connect the different account, Omni deletes the project settings for the old account from every connection.

​

Session expiry

dbt platform disconnects Omni after seven days without use. Omni uses the connection when it loads data health for a dashboard or app, when an Organization Admin clicks Test connection, and when it lists a connection’s projects. If nothing uses the connection for seven days, an Organization Admin must reconnect.

​

dbt data health on dashboards and apps

When dbt has data health for a dashboard or app, Omni shows a dbt icon with a status badge on the published dashboard or app: Click the icon to open the data health popover. It shows when the last dbt run finished, and has these sections:

• Freshness, such as Data is fresh or Data may be stale, with counts of upstream sources by freshness status
• Quality, such as Data quality passed or Data quality degraded, with counts of upstream models and tests by result, and the test coverage
• See more details, which opens the exposure’s page in dbt platform. Viewers need a dbt platform login to open it.

The popover shows counts only. It doesn’t show model or source names.

​

Show data health on your content

Push exposures from Omni for your published dashboards and apps, then merge the pull request in your dbt repository. dbt records the exposures the next time a job runs on that project. After the job runs, a new exposure can take about 15 minutes to show its health in Omni. Exposures are a snapshot. If a dashboard starts to use other dbt models, push exposures again and run a dbt platform job to update its health. If Omni can’t reach dbt platform, the indicator shows the last health that Omni read.

​

Who sees data health

Users with Restricted Querier permissions or higher on the dashboard’s or app’s model see the indicator. The indicator shows only on published dashboards and apps. It doesn’t show on drafts, on branches, or in embedded content.

​

Troubleshooting

​

Next steps

• Push exposures to dbt — Generate exposures for your published dashboards and apps, so Omni can show their data health.
• Embed dbt data health tiles — Embed dbt’s own data health tile in a dashboard or app with a service token.
• Getting started with dbt — Connect your dbt Git repository to sync metadata and author models.