> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/consume/activate/bi-tools/tableau.md).

# Tableau Desktop

Tableau Desktop connects to your semantic layer over the MySQL wire protocol.

Every dimension, measure, and join already defined in your semantic model shows up as a data source, ready for visuals — no custom SQL, no redefining measures, dimensions per workbook.

> **Want to go deeper?** For data types, best practices, limitations, governance, and FAQs, see the [Reference Guide](/concepts/foundations/activation/bi-tools/tableau.md).

## Prerequisites

Set these up once on the machine running Tableau Desktop. You only need to do this the first time.

<table><thead><tr><th width="198.50439453125">Requirement</th><th>Detail</th></tr></thead><tbody><tr><td><strong>Operating system</strong></td><td>macOS or Windows.</td></tr><tr><td><strong>Tableau Desktop</strong></td><td>Any version that supports MySQL connections. <a href="https://www.tableau.com/products/desktop/download">Download Tableau Desktop</a>.</td></tr><tr><td><strong>MySQL Connector/J</strong></td><td>Use version <code>9.2.0</code> exactly. <a href="https://mvnrepository.com/artifact/com.mysql/mysql-connector-j/9.2.0">Download from Maven Repository</a>.</td></tr><tr><td>DataOS Username</td><td>Your DataOS user ID.</td></tr><tr><td>DataOS API Token</td><td>Generate or copy a token from <a href="/pages/7rh6mFCr0rhl6vO76XjW#get-a-dataos-api-token">Before you begin</a>.</td></tr></tbody></table>

## Step 1: Install the MySQL Connector/J driver

This is a one-time setup.

1. Open [MySQL Connector/J 9.2.0](https://mvnrepository.com/artifact/com.mysql/mysql-connector-j/9.2.0).
2. In **Files**, select **jar** to download `mysql-connector-j-9.2.0.jar`.
3. Place the JAR file in the Tableau drivers folder for your operating system:

**macOS:**

```
~/Library/Tableau/Drivers/
```

**Windows:**

```
C:\Program Files\Tableau\Drivers\
```

> If the `Drivers` folder doesn't exist, create it.

Verify the file is in place:

```bash
# macOS
ls ~/Library/Tableau/Drivers
# Expected output:
mysql-connector-j-9.2.0.jar
```

4. Restart Tableau Desktop if it was open during installation.

> **Version 9.2.0 specifically.** Other versions may not be compatible with the MySQL wire protocol used by DataOS.

***

## Step 2: Download the `.tds` file

1. From the data product page, go to **Activate → BI → Tableau**.
2. Click **Download**. The download is a ZIP file containing one file and one folder.
3. Extract the ZIP. Inside, open the folder named `tables` — you'll find the `.tds` file there.

**What's in the ZIP:**

<table><thead><tr><th width="232.34747314453125">Item</th><th>What it is</th></tr></thead><tbody><tr><td><code>.tds</code> file (inside <code>tables/</code>)</td><td>Contains semantic model references. Double-click to open in Tableau Desktop.</td></tr><tr><td><code>manifest.json</code></td><td>Contains connection</td></tr></tbody></table>

> **Extract before opening.** Opening the `.tds` directly from inside the ZIP may cause connection errors.

***

## Step 3: Open the `.tds` file

Double-click the `.tds` file. Tableau Desktop opens it automatically and establishes the connection to your semantic layer.

If Tableau prompts you to enter credentials:

* **Username:** your DataOS Id
* **Password:** your DataOS API token

Click **Sign In**.

***

## Step 4: Your semantic models are loaded

Once authenticated, every available semantic model — with its dimensions and measures — appears in the left-hand **Data** pane, ready to use in sheets and dashboards.

***

You're connected. Build visualisations, dashboards, and stories directly on top of the semantic layer.

***

## Troubleshooting

For the full troubleshooting guide, see the [Reference Guide → Troubleshooting](/concepts/foundations/activation/bi-tools/tableau.md#troubleshooting).

<table><thead><tr><th width="244.73419189453125">Symptom</th><th>Quick fix</th></tr></thead><tbody><tr><td><em>"No suitable driver"</em> or driver error on connect</td><td>The JAR file is not in the correct Tableau Drivers folder. Verify the path and restart Tableau Desktop.</td></tr><tr><td><em>"Unable to connect"</em></td><td>Check that port <code>3306</code> is reachable from your machine. Check VPN or firewall rules.</td></tr><tr><td>Authentication fails</td><td>API token is incorrect or expired. Retrieve a fresh token from the Tokens tab and retry.</td></tr><tr><td><code>.tds</code> file doesn't open Tableau</td><td>Tableau Desktop is not set as the default application for <code>.tds</code> files. Right-click → Open With → Tableau Desktop.</td></tr><tr><td>Dimensions or measures missing</td><td>The semantic model schema changed after the <code>.tds</code> was downloaded. Re-download the <code>.tds</code> from the data product page.</td></tr></tbody></table>

***

## Reference

For data types, best practices, limitations, governance, and the full troubleshooting guide, see [Tableau in Concepts](/concepts/foundations/activation/bi-tools/tableau.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/consume/activate/bi-tools/tableau.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.