> 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/references/interfaces/bi-tools/tableau.md). # Tableau Desktop This page covers everything beyond the initial setup. If you're just getting started, see the [Tableau connection guide](https://github.com/moderndatacompany/dataos/tree/july-7/documentation/consume/activate/bi-tools/tableau.md). *** ### Connect via API (cURL) Use this approach to automate the `.tds` download or integrate it into a pipeline. If you prefer the UI, use the steps in the main guide instead. #### Prerequisites * `curl` installed on your machine * Your DataOS API token (see prerequisites) #### Command ```bash curl --location \ 'https:///vulcan/tenants//data-products/-/api/v1/metadata/exports/tableau' \ --header 'Authorization: Bearer ' \ --output .zip ``` **Replace:** | Placeholder | Example | Description | | ------------------ | ------------------------------- | --------------------------------------- | | `` | `heliosdev-060426.dataos.cloud` | Your DataOS fully qualified domain name | | `` | `engineering` | Your tenant name | | `` | `data-visualization-postman` | The data product resource name | | `` | `YmlfdGVzdGluZy5j...` | Your DataOS API | | **Full example:** | | | ```bash curl --location \ 'https://heliosdev-060426.dataos.cloud/vulcan/tenants/engineering/data-products/engineering-data-visualization-postman/api/v1/metadata/exports/tableau' \ --header 'Authorization: Bearer ' \ --output tableau-export.zip ``` > **Note:** The `Authorization` header uses `Bearer`, not `apikey`. Use your DataOS API token. #### Step after download Extract the ZIP. Inside, open the folder named `tables`. You'll find the `.tds` file there. ### Supported data types | Category | Data types | Status | | ------------- | -------------------------------------------------------------------------------------------- | ----------- | | **Dimension** | `time`, `string`, `number`, `boolean` | ✅ Supported | | **Measure** | `max`, `min`, `number`, `sum`, `count`, `boolean`, `string`, `time`, `avg`, `count_distinct` | ✅ Supported | *** ### Important considerations **Live connection** The connection is live. Data changes in the underlying source are reflected in Tableau without a manual refresh. **Schema changes require a re-download** If a dimension, measure, or any other semantic model element is added, modified, or removed, the `.tds` file must be re-downloaded and re-opened. Schema changes do not propagate to existing `.tds` files automatically. *** ### Best practices #### Field selection and cross-table queries Tableau does not automatically resolve transitive joins. When building visualisations: * Use fields from tables that are **directly related or logically joined** in the semantic model. * Dragging fields from unrelated tables onto the same sheet may produce incorrect results or LOD calculation errors. * All relationships are defined in the semantic model. They cannot be created or modified within Tableau when using a live connection. *** ### How the connection works When Tableau Desktop opens a `.tds` file connected to DataOS: 1. Tableau authenticates using your DataOS username and API token via a live MySQL connection on port `3306`. 2. Queries issued by Tableau (on filter changes, dashboard loads, or manual refreshes) are sent to the MySQL proxy. 3. The MySQL proxy forwards queries to the API layer, which routes them through the Transpiler. 4. The Transpiler converts semantic model queries into native SQL and sends them to the underlying data source. 5. Results are returned to Tableau for rendering. *** ### Limitations
LimitationDetail
Import / extract modeLive connection only. Tableau Extracts (.hyper) are not supported for model-first data products.
Schema changesDo not propagate automatically. Re-download the .tds after any model change.
One .tds per data productEach data product requires its own .tds file and connection.
*** ### Governance **Authentication and authorisation** Tableau authenticates using the DataOS username and API token of the connecting user. Vulcan enforces data policies based on that user's group memberships. **Column-level and row-level policies** Columns restricted by Vulcan data policies are hidden automatically. They do not appear in the Data pane and cannot be added to a sheet. Row-level filters are applied at the semantic layer before results reach Tableau. **Example:** A user in the `Analyst` group restricted from viewing `annual_salary` will not see that field in the Tableau Data pane. The restriction is enforced by Vulcan, not by Tableau. It cannot be bypassed from within the workbook. *** ### Troubleshooting #### "No suitable driver" or driver error on connect The MySQL Connector/J JAR is not in the correct Tableau Drivers folder. * **macOS:** confirm `mysql-connector-j-9.2.0.jar` is in `~/Library/Tableau/Drivers/` * **Windows:** confirm it is in `C:\Program Files\Tableau\Drivers\` * Restart Tableau Desktop after placing the file. * Verify you downloaded the JAR (not the POM) from the Maven Repository page. *** #### Authentication fails The API token is incorrect, expired, or copied with extra whitespace. * Retrieve a fresh token from **Profile icon → your name → Tokens tab**. * Copy it using the eye icon and paste it directly. Avoid manual typing. * Confirm the username is your DataOS Id (the **Id** field), not your email address. *** #### `.tds` file doesn't open Tableau Desktop Tableau Desktop is not set as the default application for `.tds` files. * **macOS:** right-click the file → **Open With → Tableau Desktop**. * **Windows:** right-click → **Open with → Choose another app → Tableau Desktop**. To set it as the permanent default, select **Always use this app**. *** #### Dimensions or measures missing from the Data pane The semantic model schema changed after the `.tds` was downloaded. * Re-download the `.tds` ZIP from the data product page. * Extract and open the new `.tds` file. * In Tableau, you may need to re-map any broken field references in existing sheets. *** ### FAQs **What version of MySQL Connector/J is required?** Version 9.2.0 specifically. Download the JAR from [Maven Repository](https://mvnrepository.com/artifact/com.mysql/mysql-connector-j/9.2.0). Under **Files**, click **jar**. *** **What does the `.tds` file contain?** A `.tds` (Tableau Data Source) file is an XML file that stores the connection settings: host, port, database, authentication method, and semantic model references. It does not contain any data. Opening it in Tableau establishes a live connection to DataOS. *** **Can I share my workbook with a colleague?** Yes. Save the workbook as a `.twbx` (Tableau Packaged Workbook) to embed the connection definition. Your colleague will need their own DataOS credentials to authenticate when they open it. *** **What happens when the semantic model schema changes?** The existing `.tds` file becomes stale. Re-download the `.tds` ZIP from the data product page, extract the new `.tds` from the `tables/` folder, and open it. Re-map any broken field references in existing sheets. *** **Does each data product need its own `.tds` file?** Yes. Each model-first data product has its own `.tds` file with its own connection settings. Download a separate `.tds` for each product you want to connect to. *** **What connection mode is used?** Live connection. Tableau queries the DataOS semantic layer directly on every interaction. *** **Where does computation happen?** In two layers: the Transpiler converts semantic model queries into native SQL; the underlying data source performs retrieval and aggregation. Visual load time depends on source performance. --- # 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/references/interfaces/bi-tools/tableau.md?ask=&goal= ``` `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.