Skip to main content

dbt integration

If you use dbt Cloud, Hex can use metadata from your dbt project to enrich the schema browser with additional informaton.

Hex will fetch the following information from your scheduled jobs in dbt Cloud:

  • Model, source and column descriptions and tests
  • When the model was last updated
  • Any source freshness tests
  • Links to the relevant page of your deployed docs site in dbt Cloud

Once the dbt integration is configured, tables in the schema browser that are part of a model or defined as a source in dbt will display their most recent job execution date, source freshness, and the status of any tests configured on the model.

This metadata will be refreshed automatically for all tables in a data connection associated with dbt models or sources, and only needs to be configured once per connection.


If a new table has been added to a data connection, you will need to refresh the Schema browser in order to see the new table.

Configuring the dbt integration

Each data connection can be individually configured to integrate with dbt. From the connection settings, you can toggle on the dbt integration and provide your credentials. Hex will automatically find the relevant schemas and tables as modeled in dbt.

Account ID and Project ID can be most easily found in the URL of the "Jobs" page for your project, following this structure:<ACCOUNT_ID>/projects/<PROJECT_ID>/jobs/

The service token must be have both the "Metadata Only" and "Job Admin" permissions. To generate a service token:

  1. Head to the Account Settings view in dbt Cloud.
  2. Click the Service Account tokens page and select "New Token".
  3. Name the token ("Hex dbt integration" is a good starting point), and add the "Metadata Only" and "Job Admin" permissions.
  4. Add the the token to the Hex connection.

Note: After a token is generated, it won't be able to be viewed again so either add it to Hex immediately, or store it somewhere very safe!

Supported connection types

  • BigQuery
  • Databricks
  • PostgreSQL
  • Redshift
  • Snowflake


If you're experiencing errors, check the error message by hovering over the warning icon in the schema browser.

Error typeTroubleshooting
No jobs found for this projectThe dbt Cloud integration pulls information from jobs invoked via the dbt Cloud Scheduler. Check that at least one job in dbt Cloud has the "generate docs" checkbox enabled (more info), and that it has been run successfully.
401 UnauthorizedThis error message often means the token provided on the connection is invalid, or does not have the correct permissions. To fix this, follow the steps in the above section on Configuring the dbt integration to create a new token.
All other errorsFor all other errors, first check the dbt Cloud status page to see if there is an active issue. Then contact dbt support for more assistance.