dbt Semantic Layer | Tableau Exchange

dbt Semantic Layer


by dbt Labs


The dbt Semantic Layer is a product by dbt Labs that allows organizations to centrally define metrics to ensure consistent access in downstream data applications. It can query data dynamically and automatically handles joins through sophisticated SQL generation. You can find more documentation on the dbt Semantic Layer here.

Use the dbt Semantic Layer connector in Tableau to make a live connection into the dbt Semantic Layer, query the metrics defined in code, and create and publish dashboards with trusted data from the source of truth. Using the dbt Semantic Layer connector for Tableau, you can reduce your dependencies on data extracts without compromising governance and create a simplified interface in Tableau, by moving more of your business logic into code.



  • You have a dbt Cloud Team or Enterprise account, and your dbt version is v1.6 or higher.
  • You have configured the dbt Semantic Layer in dbt Cloud
  • You are using Tableau Desktop version 2021.1 or greater

JDBC Driver Download the JDBC driver to the folder based on your operating system:

  • Windows: `C:\Program Files\Tableau\Drivers`
  • Mac: `~/Library/Tableau/Drivers or /Library/JDBC or ~/Library/JDBC`
  • Linux: `/opt/tableau/tableau_driver/jdbc`

Taco File Download the Taco file and place it in the default directory

  • Desktop Windows: C:\Users\[YourUser]\Documents\My Tableau Repository\Connectors
  • Desktop MacOS: /Users/[YourUser]/Documents/My Tableau Repository/Connectors
  • Server Windows: C:\ProgramData\Tableau\Tableau Server\data\tabsvc\vizqlserver\Connectors
  • Server Linux: [Your Tableau Server Install Directory]/data/tabsvc/vizqlserver/Connectors

Restart Tableau Desktop or Tableau Server and find the dbt Semantic Layer by dbt Labs connector on the left-hand side. Connect with your Host, Environment ID, and Service Token information dbt Cloud provides during Semantic Layer configuration.

Things to note


  • All metrics are shown as using the "SUM" aggregation type in Tableau's UI, and this cannot be altered using Tableau's interface.
  • The dbt Semantic Layer controls the aggregation type in code and it is intentionally fixed. Keep in mind that the underlying aggregation in the dbt Semantic Layer might not be "SUM" ("SUM" is Tableau's default).

Data sources and display

  • In the "ALL" data source, Tableau surfaces all metrics and dimensions from the dbt Semantic Layer on the left-hand side. Note, that not all metrics and dimensions can be combined. You will receive an error message if a particular dimension cannot be sliced with a metric (or vice versa). You can use saved queries for smaller pieces of data that you want to combine.
  • To display available metrics and dimensions, dbt Semantic Layer returns metadata for a fake table with the dimensions and metrics as 'columns' on this table. Because of this, you can't actually query this table for previews or extracts.

Calculations and querying

  • Certain Table calculations like "Totals" and "Percent Of" may not be accurate when using metrics aggregated in a non-additive way (such as count distinct)
  • In any of our Semantic Layer interfaces (not only Tableau), you must include a time dimension when working with any cumulative metric that has a time window or granularity.
  • We can support calculated fields for creating parameter filters or dynamically selecting metrics and dimensions. However, other uses of calculated fields are not supported.
    • Note: For calculated field use cases that are not currently covered, please reach out to dbt Support and share them so we can further understand.
  • When using saved queries that include filters, we will automatically apply any filters that the query has.

Unsupported Functionality

The following Tableau features aren't supported at this time, however, the dbt Semantic Layer may support some of this functionality in a future release:

  • Updating the data source page
  • Using "Extract" mode to view your data
  • Unioning Tables
  • Writing Custom SQL / Initial SQL
  • Table Extensions
  • Cross-Database Joins
  • Some functions in Analysis --> Create Calculated Field
  • Filtering on a Date Part time dimension for a Cumulative metric type
  • Changing your date dimension to use "Week Number"
  • Performing joins between tables that the dbt Semantic Layer creates. It handles joins for you, so there's no need to join components in the dbt Semantic Layer. Note, that you can join tables from the dbt Semantic Layer to ones outside your data platform.

For more information, please see dbt Labs documentation on the connector.

Tech Specifications

Works with
Tableau 2020.4 and later