> 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/concepts/foundations/activation/bi-tools/tableau.md). # Tableau This page covers everything beyond the initial setup. If you're just getting started, see the Tableau [connection guide](/consume/activate/bi-tools/tableau.md). ## Download the `.tds` Project You can download the Tableau project (`.tds`) using any of the following methods: 1. **API Documentation** – Download the project directly from your DataOS instance using the API documentation. See the [API Documentation](/concepts/foundations/activation/apis.md). 2. **Postman Collection** – Download the Postman collection and use the **Discover → Metadata → Export → Tableau** endpoint. See the [Postman Collection](/concepts/foundations/activation/apis/getting-started/postman-collection.md). 3. **SDK** – Download the project programmatically using the SDK. See the [SDK Documentation](/concepts/foundations/activation/apis/getting-started/sdks.md). 4. **cURL** – Use the cURL command shown below. ### 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 the Placeholders | Placeholder | Example | Description | | --------------------- | ------------------------------- | --------------------------------------- | | `` | `heliosdev-060426.dataos.cloud` | Your DataOS fully qualified domain name | | `` | `engineering` | Your tenant name | | `` | `data-visualization` | The name of the data product | | `` | `YmlfdGVzdGluZy5j...` | Your DataOS API token | ```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 `apitoken`. 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 | > Note: Measures with boolean, string, and time types may appear under dimensions in Tableau. To use a time field correctly as either a measure or dimension, select Exact Date from the field menu. *** callout - Measure type = boolean,string and time appeared under the dimensions, to use time as a measure or dimesnion use exact date format ### 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 relationships are evaluated dynamically at query time based on the fields used in the visualization. While Tableau automatically determines the required joins, the underlying semantic model must provide a valid relationship path between the selected tables. When building visualizations: * Use fields from tables that are **directly related** or have a **valid relationship path** in the semantic model. * Prefer selecting **measures from the central fact table** and **dimensions from related dimension tables** whenever possible. * If a measure is selected from one table and a dimension from another, Tableau attempts to resolve the relationship path dynamically. If the semantic model cannot resolve the traversal, the query may fail with a **"Can't find join path"** error. * Ensure every table required for your analysis is connected through a continuous relationship path. Missing or unsupported relationship paths can prevent Tableau from generating a valid query. * Relationships are defined in the semantic model and cannot be created or modified within Tableau when using a live connection. * If a visualization requires combining tables that are not connected through a valid relationship path, consider redesigning the semantic model to expose the required relationships. *** ### 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 | Limitation | Detail | | ------------------------------- | -------------------------------------------------------------------------------------------------- | | **Import / extract mode** | Live connection only. Tableau Extracts (`.hyper`) are not supported for model-first data products. | | **Schema changes** | Do not propagate automatically. Re-download the `.tds` after any model change. | | **One `.tds` per data product** | Each 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. *** ### 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. *** #### 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. --- # 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/concepts/foundations/activation/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.