How to connect Tableau to the dbt Semantic Layer

The dbt Semantic Layer has a Tableau connector: metrics and dimensions appear as fields of a live data source, and every viz is turned into a Semantic Layer query. Tableau users keep their workflow; the definitions come from dbt. A few Tableau features work differently, and knowing them in advance saves a confusing afternoon.

Copy and paste

What you need:

• a dbt platform Starter or Enterprise account with the Semantic Layer configured;
• the host, the environment ID and a service token (or a personal access token) from the project’s Semantic Layer page;
• Tableau Desktop 2021.1 or later, Tableau Server, or Tableau Cloud.

Tableau Desktop on a Mac, connector and JDBC driver:

# connector (.taco), from dbt Labs' GitHub releases
mkdir -p ~/Documents/"My Tableau Repository"/Connectors
curl -L -o ~/Documents/"My Tableau Repository"/Connectors/dbt_semantic_layer.taco \
  https://github.com/dbt-labs/semantic-layer-tableau-connector/releases/latest/download/dbt_semantic_layer.taco
# JDBC driver: Arrow Flight SQL, version 12.0.0 or later, from Maven
mkdir -p ~/Library/Tableau/Drivers
curl -L -o ~/Library/Tableau/Drivers/flight-sql-jdbc-driver-12.0.0.jar \
  "https://search.maven.org/remotecontent?filepath=org/apache/arrow/flight-sql-jdbc-driver/12.0.0/flight-sql-jdbc-driver-12.0.0.jar"

On Windows the folders are Documents\My Tableau Repository\Connectors and C:\Program Files\Tableau\Drivers. Tableau Cloud manages the connector itself; it is also on Tableau Exchange.

Connecting

1. Restart Tableau and choose Semantic Layer by dbt Labs in the list of connectors on the left.
2. Enter the host, the environment ID and the token. On Tableau Server the dialog may ask for “User” and “Password”: the user is the environment ID and the password is the token.
3. Pick the ALL data source for every metric, dimension and entity, or a saved query, which appears as its own data source with its filters applied.
4. Go straight to a worksheet. The data source page can’t preview the data: it is a stand-in table that only carries the field list.

Tableau habits that change

• Live only. Extracts are not supported, so dashboards query the warehouse through the Semantic Layer on every load. Use the Semantic Layer cache, and keep heavy dashboards on saved queries.
• Every metric shows as SUM. The aggregation is fixed by the metric’s definition in dbt; the SUM in the shelf is a label. Don’t try to change it to AVG or COUNTD in Tableau: define another metric instead.
• Totals and Percent of Total are table calculations on what Tableau receives. For non-additive metrics (distinct counts, averages, ratios) they are wrong, because summing per-row values is not the metric’s definition. Query the total as a separate row or worksheet instead.
• Not every metric combines with every dimension. The ALL data source lists everything, and Tableau shows an error when a dimension can’t reach a metric. That is the fan-out rule, not a broken connection.
• Cumulative metrics need a date on the view: YTD or rolling totals without metric_time fail.
• Calculated fields are supported for parameters and for switching metrics or dimensions; other calculations, custom SQL, initial SQL, unions and cross-database joins are not.
• Standard grains only. Custom granularities such as fiscal years are not available in Tableau today; dbt suggests the APIs for those. “Week Number” date parts are not supported either.
• No labels. Tableau shows metric names, not the label set in dbt, so choose readable metric names.

Publishing

Publish workbooks to Tableau Server or Cloud as usual. With a service token embedded, every viewer queries with the Semantic Layer credential behind that token; with personal access tokens, each user connects with their own. Plan the tokens the way you plan Tableau’s data source credentials.

“Failed ALPN”

Behind a corporate VPN or proxy (Zscaler, Check Point), the connection can fail with Failed ALPN. The Semantic Layer uses gRPC over HTTP/2, which some proxies break during the TLS handshake. Ask for an SSL inspection exception for the dbt domain, or for ALPN to be allowed.

Based on the dbt platform documentation (October 2026).