> ## Documentation Index
> Fetch the complete documentation index at: https://honeydew.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tableau Integration

Tableau connects to Honeydew via JDBC or ODBC drivers using the Trino protocol.

## Tableau Cloud / Server

### Tableau Server Connector & Driver setup

<Note>
  You can skip this step if using Tableau Cloud.
</Note>

Follow these steps to connect to Honeydew:

<Note>
  If you are running Tableau Server as a multi-node cluster, you must install the JDBC driver and the Honeydew connector on each node.
</Note>

1. If Tableau is open, close it, and exit.

2. Download the [latest Trino JDBC driver](https://repo.maven.apache.org/maven2/io/trino/trino-jdbc/480/trino-jdbc-480.jar).

3. Place the JDBC driver file in the following location according to your operating system:

   * **Linux**: `/opt/tableau/tableau_driver/jdbc` (if the `jdbc` folder does not exist, create it first)
   * **Windows**: `C:\Program Files\Tableau\Drivers`

   Do not store more than one Trino JDBC driver in the directory. Delete any older Trino drivers when you update to a newer version.
   Connections to all connected data sources are made through the JDBC driver.

4. Get the **Honeydew\.taco** file from Honeydew support (reach out to [support@honeydew.cloud](mailto:support@honeydew.cloud) to get one).

5. Move the data connector **Honeydew\.taco** file to the following location:
   * **Linux**: `/opt/tableau/connectors` (if the `connectors` folder does not exist, create it first)
   * **Windows**: `C:\Program Files\Tableau\Connectors`

6. Restart Tableau Server and log in.

7. Click Create, then select Workbook. In the Connect to Data pane, click the Connectors tab.

8. Follow the steps to [set up a new datasource](#setting-up-a-new-data-source).
   If this is your first time using this connector, a Connector Details dialog will pop up.
   Click the Install and Restart Tableau button.

### Adding an OAuth Client For Honeydew

<Note>
  If you would like to use OAuth (SSO) to connect to Honeydew, you need to register an OAuth client
  in Tableau Cloud or Tableau Server. This step is optional but recommended if you want each Tableau
  user to connect to Honeydew using their own Honeydew credentials.
</Note>

<Tabs>
  <Tab title="Tableau Server">
    1. Sign in to Tableau Server as a site admin and navigate to the **Settings** page
    2. Under the **General** tab, scroll down to the **OAuth Clients Registry** section
    3. Click **Add OAuth Client**
    4. In **Connection Type**, select the **Honeydew Semantic Layer by Honeydew Data** option
    5. For **OAuth Provider**, keep **default**
    6. Leave **OAuth Instance URL** empty
    7. For **Client ID**, enter `honeydew-jdbc-connector`
    8. For **Client Secret**, enter `honeydew-jdbc-connector` (or any other non-empty value - it is not used)
    9. Make a note of the **Redirect URL** - you will need to send it to Honeydew support to enable OAuth for your Tableau instance
    10. Click **Add OAuth Client**
  </Tab>

  <Tab title="Tableau Cloud">
    1. Sign in to Tableau Cloud as a site admin and navigate to the **Settings** page

    2. Under the **General** tab, scroll down to the **OAuth Clients Registry** section

    3. Click **Add OAuth Client**

    4. In **Connection Type**, select **Starburst Enterprise**

    5. For **OAuth Provider**, keep **default**

    6. Leave **OAuth Config Id** empty - it is taken from the `oauthConfigId` value
       in the uploaded config file

    7. For **Client ID**, enter `honeydew-jdbc-connector`

    8. For **Client Secret**, enter `honeydew-jdbc-connector` (or any other non-empty value - it is not used)

    9. Make a note of the **Redirect URL** - you will need to send it to Honeydew support to enable OAuth for your Tableau instance.
       It is your Tableau instance URL ending with `/auth/add_oauth_token`, for example
       `https://<your_tableau_instance>.tableau.com/auth/add_oauth_token`.

    10. For **Choose OAuth Config File**, save the following XML to a file and upload it:

            <Note>
              If your organization uses a custom JDBC hostname, replace `jdbc.honeydew.cloud` in the
              `authUri` and `tokenUri` values below with your custom domain.
            </Note>

        ```xml theme={null}
        <?xml version="1.0" encoding="utf-8"?>
        <pluginOAuthConfig>
            <!-- dbclass must correspond to the class registered in manifest.xml -->
            <dbclass>trino_jdbc</dbclass>

            <oauthConfigId>custom_honeydew</oauthConfigId>

            <!-- Auth0 URIs -->
            <authUri>https://jdbc.honeydew.cloud/oauth/authorize</authUri>
            <tokenUri>https://jdbc.honeydew.cloud/oauth/token</tokenUri>

            <scopes>openid</scopes>
            <scopes>profile</scopes>
            <scopes>email</scopes>
            <scopes>offline_access</scopes>

            <!-- OAuth capabilities based on WDC documentation -->
            <capabilities>
                <entry>
                    <key>OAUTH_CAP_SUPPORTS_CUSTOM_DOMAIN</key>
                    <value>false</value>
                </entry>
                <entry>
                    <key>OAUTH_CAP_FIXED_PORT_IN_CALLBACK_URL</key>
                    <value>true</value>
                </entry>
                <entry>
                    <key>OAUTH_CAP_CLIENT_SECRET_IN_URL_QUERY_PARAM</key>
                    <value>true</value>
                </entry>
                <entry>
                    <key>OAUTH_CAP_PKCE_REQUIRES_CODE_CHALLENGE_METHOD</key>
                    <value>true</value>
                </entry>
                <entry>
                    <key>OAUTH_CAP_REQUIRE_PKCE</key>
                    <value>true</value>
                </entry>
                <entry>
                    <key>OAUTH_CAP_SUPPORTS_STATE</key>
                    <value>true</value>
                </entry>
                <entry>
                    <key>OAUTH_CAP_SUPPORTS_GET_USERINFO_FROM_ID_TOKEN</key>
                    <value>true</value>
                </entry>
            </capabilities>

            <!-- Map Tableau recognized attribute "key" to OAuth response attribute "value" -->
            <accessTokenResponseMaps>
                <entry>
                    <key>ACCESSTOKEN</key>
                    <value>access_token</value>
                </entry>
                <entry>
                    <key>REFRESHTOKEN</key>
                    <value>refresh_token</value>
                </entry>
                <entry>
                    <key>access-token-issue-time</key>
                    <value>issued_at</value>
                </entry>
                <entry>
                    <key>access-token-expires-in</key>
                    <value>expires_in</value>
                </entry>
                <entry>
                    <key>id-token</key>
                    <value>id_token</value>
                </entry>
                <entry>
                    <key>username</key>
                    <value>email</value>
                </entry>
            </accessTokenResponseMaps>
        </pluginOAuthConfig>
        ```

    11. Click **Add OAuth Client**. The client is added to the OAuth Clients Registry list.

    12. Scroll down to the bottom of the Settings page and click **Save**.
        The client is not persisted until you save the page.

    <Note>
      Once a custom OAuth client is registered, Tableau uses it for all new Starburst Enterprise OAuth
      credentials on the site. Credentials saved before the change keep working temporarily — re-add them
      to switch to the new client.
    </Note>
  </Tab>
</Tabs>

### API Access Setup

Honeydew connects to Tableau Cloud or Server using Tableau REST APIs.
It uses Tableau [Personal Access Tokens](https://help.tableau.com/current/online/en-us/security_personal_access_tokens.htm).

<Steps>
  <Step title="Enable PAT in Tableau Cloud or Server">
    1. Sign in to Tableau Cloud or Tableau Server as a site admin and navigate to the Settings page.
    2. Under the Personal Access Tokens section, select the Enable personal access tokens check box if not already selected.
  </Step>

  <Step title="Set a PAT in Tableau for Honeydew">
    1. Sign in as the user that will be used for Honeydew API connectivity

           <Note>
             The Tableau user for API must have the ability to change and update published data sources.
           </Note>

    2. Create a PAT for the Honeydew connectivity using [My Account Settings](https://help.tableau.com/current/pro/desktop/en-us/useracct.htm#create-and-manage-personal-access-tokens)

    3. Under Personal Access Tokens, enter a descriptive name (i.e. `honeydew_api`) for your token in the Token Name field,
       and then click **Create Token**.

    4. In the Personal Access Token dialog box, click the **Copy Secret** button.

    5. Keep the token name and the secret for the next step.
  </Step>

  <Step title="Configure Honeydew with the PAT">
    1. Sign in to Honeydew with a user that has administrator privileges
    2. Open the user settings menu
    3. Navigate to **Tableau** → **Settings**
    4. Enter the following information

    <Tabs>
      <Tab title="Tableau Cloud">
        * **Server**: the server URL, i.e. `https://10ax.online.tableau.com` if your
          Tableau domain is `https://10ax.online.tableau.com/t/yoursite/`
        * **Site**: the site name, i.e. `yoursite` if your Tableau domain is
          `https://10ax.online.tableau.com/t/yoursite/`
        * The PAT name and secret as generated in the previous step
      </Tab>

      <Tab title="Tableau Server">
        * **Server**: the URL of your internal Tableau Server instance, i.e.
          `https://tableau.example.com`

                  <Note>
                    Honeydew calls the Tableau REST API over HTTPS, on the same gateway endpoint as the
                    Tableau web UI. If your Tableau Server is not reachable from Honeydew, expose it through
                    a reverse proxy that terminates TLS. Tableau recommends not placing Tableau Server
                    directly on the internet or in a DMZ — see
                    [Configuring Proxies and Load Balancers for Tableau Server](https://help.tableau.com/current/server/en-us/proxy.htm).
                    Then restrict inbound access by allowlisting the Honeydew client IP addresses at your
                    firewall or reverse proxy.

                    For the Honeydew Cloud deployment, the following IP addresses are used:

                    * `34.86.209.90`
                    * `34.145.147.92`

                    If you are using a private Honeydew deployment, the IP addresses will be different.
                    You can find them in the connection screens in the
                    [Honeydew App settings page](https://app.honeydew.cloud/settings).
                  </Note>
        * **Site**: leave empty when using the Default site, or the site name when
          connecting to a named site
        * The PAT name and secret as generated in the previous step
      </Tab>
    </Tabs>
  </Step>

  <Step title="Enable Tableau Catalog Integration">
    If you have the [Tableau Data Management](https://www.tableau.com/products/data-management) feature enabled in your
    Tableau account, please ask [support@honeydew.ai](mailto:support@honeydew.ai) to enable the Tableau Catalog Integration.

    <Tip>
      Honeydew synchronizes all metadata (such as metric descriptions) to a Tableau Data Source.

      When Tableau Catalog is enabled, Honeydew synchronizes metadata there as well.
    </Tip>
  </Step>
</Steps>

### Setting up a New Data Source

Tableau Data Sources are mapped to a Honeydew workspace, branch and domain.

<Tip>
  Once published, data sources can be refreshed from Honeydew (see next section).
</Tip>

There are a few ways to create a new data source managed by Honeydew:

#### Setting up a New Data Source in Honeydew UI

<Tip>
  This is the easiest and the recommended way to create a new data source in Tableau.
</Tip>

1. In Honeydew UI, go to the **Branch** menu → **Branch Integrations** → **Tableau** → **Sync to Tableau**.
2. Select the domain to use for the data source.
3. Select the Tableau project to place the data source in.
4. Provide a name for the data source.
5. Click **Publish**.
6. Open the data source in Tableau Cloud or Tableau Server.
7. Provide the credentials for the data source.

   <Tip>
     1. For **Tableau Cloud** and **Tableau Server**, you can either use an [API Key](/docs/access-control/api-keys)
        to connect to Honeydew through a central service account, or use **OAuth (SSO)** to allow each user
        to connect to Honeydew using their own credentials. In cases where you want to make sure each user
        uses their own Snowflake credentials, and have defined per-user Snowflake credentials in Honeydew,
        use the **OAuth (SSO)** method.
        Make sure to register the OAuth client as [described above](#adding-an-oauth-client-for-honeydew).
     2. For enhanced security and audit trail, consider using [per-user API keys](/docs/access-control/api-keys/#per-user-api-keys)
        to maintain individual user identification and enable integration with
        per-user Snowflake credentials.
   </Tip>

   ```
   User: api key (or Honeydew user)
   Password: api secret (or Honeydew password)
   ```

#### Setting up a New Data Source in Tableau Desktop

1. In Honeydew UI, go to the **Branch** menu → **Branch Integrations** → **Tableau** → **Download datasource**.
2. Select the domain to use for the data source.
3. Click **Download** to download the data source file.
4. Open the data source file in Tableau Desktop and provide the credentials for the data source.

   <Tip>
     1. For **Tableau Cloud** and **Tableau Server**, you can either use an [API Key](/docs/access-control/api-keys)
        to connect to Honeydew through a central service account, or use **OAuth (SSO)** to allow each user
        to connect to Honeydew using their own credentials. In cases where you want to make sure each user
        uses their own Snowflake credentials, and have defined per-user Snowflake credentials in Honeydew,
        use the **OAuth (SSO)** method.
        Make sure to register the OAuth client as [described above](#adding-an-oauth-client-for-honeydew).
   </Tip>

   ```
   User: api key (or Honeydew user)
   Password: api secret (or Honeydew password)
   ```
5. Publish the data source to Tableau Cloud or Tableau Server.

#### Setting up a New Data Source in Tableau Cloud or Tableau Server

1. Create a new data source: **New** → **Published Data Source**

2. Choose data from **Connectors**

3. <Tabs>
     <Tab title="Tableau Cloud">
       Choose a **Trino** connection (use **Starburst Enterprise** in Tableau Cloud).
       You can connect with either an API key (or username and password) or **OAuth (SSO)**.

       <Tip>
         Use an [API Key](/docs/access-control/api-keys) to connect through a central service account,
         or use **OAuth (SSO)** so each user connects to Honeydew using their own credentials. The
         OAuth method is useful when you have defined per-user Snowflake credentials in Honeydew and
         want each user to use their own. To use OAuth, first register the OAuth client as
         [described above](#adding-an-oauth-client-for-honeydew).
       </Tip>

       With an **API key** (or username and password), provide the following:

       ```
       Server: jdbc.honeydew.cloud
       Port: 443
       User: api key (or Honeydew user)
       Password: api secret (or Honeydew password)
       Require SSL: yes
       ```

       With **OAuth (SSO)**, provide the following:

       * **Server**: `jdbc.honeydew.cloud`
       * **Port**: `443`
       * **Authentication**: choose **OAuth (SSO)**
       * **OAuth Instance URL**: `https://jdbc.honeydew.cloud`
         (use your own JDBC URL if your organization uses a custom hostname -
         it must match the JDBC Server endpoint)
       * **Require SSL**: check this option

       <Note>
         If your organization uses a custom hostname for the JDBC connection,
         you can locate it in the Honeydew UI, under the **JDBC** section in **Settings**.
       </Note>

       <Note>
         Honeydew SQL interface uses the Trino protocol for Tableau connectivity. There is no actual
         Trino running in Honeydew - all queries are executed in Snowflake.
       </Note>
     </Tab>

     <Tab title="Tableau Server / Desktop">
       Choose the **Honeydew Semantic Layer by Honeydew Data** connection, and provide credentials.
       You can choose between **Username and Password** or **OAuth (SSO)** authentication methods.

       <Tip>
         You can either use an [API Key](/docs/access-control/api-keys) to connect to Honeydew through a central service account,
         or to use **OAuth (SSO)** to connect to Honeydew, so as to allow each user to connect to Honeydew
         using their own credentials. In cases where you want to make sure each user uses their own
         Snowflake credentials, and have defined per-user Snowflake credentials in Honeydew, use the **OAuth (SSO)** method.
         Make sure to configure the OAuth client in Tableau Server as [described above](#adding-an-oauth-client-for-honeydew).
       </Tip>

       With **Username and Password**, provide the following:

       ```
       Server: jdbc.honeydew.cloud
       Port: 443
       User: api key (or Honeydew user)
       Password: api secret (or Honeydew password)
       Require SSL: yes
       ```

       With **OAuth (SSO)**, provide the following:

       * **Server**: `jdbc.honeydew.cloud`
       * **Port**: `443`
       * **Authentication**: choose **OAuth (SSO)**
       * **OAuth Instance URL**: `https://jdbc.honeydew.cloud`
         (use your own JDBC URL if your organization uses a custom hostname -
         it must match the JDBC Server endpoint)
       * **Require SSL**: check this option

       <Note>
         If your organization uses a custom hostname for the JDBC connection,
         you can locate it in the Honeydew UI, under the **JDBC** section in **Settings**.
       </Note>
     </Tab>
   </Tabs>

The following steps are same for Tableau Cloud, Tableau Server and Tableau Desktop:

4. Upon connecting, choose a **Catalog**

   * Catalog for the production branch is the name of the workspace  (for example `tpch_demo` for TPC-H demo).
   * Catalog for a development branch called `branch` is `workspace__branch` (for example `tpch_demo__dev` for the
     `dev` branch in `tpch_demo` workspace).

5. With a catalog, choose a **Schema** and a **Table**

   * Schema for domains is called `domains`, and tables are domain names
   * Schema for all of the semantic layer at once is called `world`, and the table name is `world` as well.

   <Tip>
     Use [domains](/docs/domains) to control the metadata and data availible in a particular Data Source
   </Tip>

6. Run **Publish Data Source**.

   <Note>
     Data from Honeydew can be queried by Tableau at this point, but it does not have metadata yet, like
     folders, descriptions or [Tableau-specific metadata](/docs/integration/bi-tools/tableau#tableau-specific-metadata).

     The next step adds metadata.
   </Note>

The following step is supported only in **Tableau Cloud** and **Tableau Server** (not in **Tableau Desktop**):

7. From within Honeydew UI, choose the same workspace and branch, and run **Tableau** → **Sync to Tableau**

   <Warning>
     1. If you have not set up Tableau API connectivity with a PAT, this step will fail
     2. If you are using **Tableau Server**, you might have to configure your network so
        Honeydew can reach your **Tableau Server** instance. See the network requirements
        in [API Access Setup](#api-access-setup).
   </Warning>

### Using a Published Data Source

Workbooks in Tableau can operate on Published Data Sources. To use a Honeydew-managed Tableau Data Source:

1. Navigate to the published data source
2. Create a new workbook: **New** → **Workbook Using This Data Source**
3. Enter your Honeydew credentials in the Workbook
4. Choose **Group By Folder** in the workbook view

   <Tip>
     Honeydew semantic layer presents itself to Tableau as a single virtual table. To see the entity structure
     move to folder view, as Honeydew will put every attribute or metric in its corresponding entity folder.

     Attributes or metrics with a user-defined folder will be placed there instead of their entity folder.
   </Tip>

### Refreshing a Published Data Source

Changes in calculations reflect automatically and immediately in Tableau.

<Tip>
  Connect a Tableau to a development branch, and any logic changes in Honeydew will
  immediately reflect in your workbook.

  That allows for a quick experimentation workflow with Tableau on Honeydew semantics.
</Tip>

Any other change will not reflect in Tableau until running **Tableau** → **Sync to Tableau**.

In particular, following changes requires syncing:

1. Changing metadata: descriptions, folders, display names and Tableau-specific metadata
2. Adding new attributes or metrics
3. Renaming or removing attributes or metrics
4. Changing the entities or fields that participate in a domain

Once a published data source is refreshed, all workbooks using that data source update as well.

<Note>
  In an open workbook, might need to click the data source → **Refresh data source** to see changes.
</Note>

## Tableau Desktop

When working with Tableau Desktop, you can use a local data source or a published data source from Tableau Cloud or Server.

### Connector & Driver setup

Use the following steps to connect in Tableau Desktop, either to a local Honeydew data source or to one published on Tableau Server:

1. If Tableau Desktop is open, close it, and exit.
2. Download the [latest Trino JDBC driver](https://repo.maven.apache.org/maven2/io/trino/trino-jdbc/480/trino-jdbc-480.jar).
3. Place the JDBC driver file in the following location according to your operating system:
   * **MacOS**: `~/Library/Tableau/Drivers` (if the folder does not exist, create it first)
   * **Windows**: `C:\Program Files\Tableau\Drivers`
     Do not store more than one Trino JDBC driver in the directory. Delete any older Trino drivers when you update to a newer version.
     Connections to all connected data sources are made through the JDBC driver.
4. Get the **Honeydew\.taco** file from Honeydew support (reach out to [support@honeydew.cloud](mailto:support@honeydew.cloud) to get one).
5. Move the data connector **Honeydew\.taco** file to the following location:
   * **MacOS**: `~/Documents/My Tableau Repository/Connectors` (if the `Connectors` folder does not exist, create it first)
   * **Windows**: `C:\Users\<user>\Documents\My Tableau Repository\Connectors`
6. Restart Tableau Desktop and log in.

If you would like to connect Tableau Desktop to a data source published to Tableau Cloud,
you would also need to install a **Trino** connector:

1. If Tableau Desktop is open, close it, and exit.
2. Download the latest Trino ("Starburst") connector from the [Tableau exchange](https://exchange.tableau.com/products/274) website.
   You might be required to login to your Tableau account to download the connector.
   <Tip>
     If you are using a Tableau Desktop version older than 2024.2, please contact Tableau support to get an earlier version of the driver.
   </Tip>
3. Move the downloaded data connector file to the following location:
   * **MacOS**: `~/Documents/My Tableau Repository/Connectors` (if the `Connectors` folder does not exist, create it first)
   * **Windows**: `C:\Users\<user>\Documents\My Tableau Repository\Connectors`
4. Restart Tableau Desktop and log in.

### Local Data Source

#### Setting up a New Local Data Source

<Tip>
  A local data source is only availible on the machine where Tableau Desktop is installed. If
  operating in a shared environment, use the Published Data Source flow.
</Tip>

To set up a local data source on a chosen workspace, branch and domain:

In Honeydew,

1. Choose the workspace and branch to use.
2. Choose the domain to use.
3. Download data source from Honeydew by running run **Tableau** → **Download datasource**

In your desktop environment,

4. Copy the data source to the **Datasources** folder under your Tableau repository
   * Usually in your `Documents/My Tableau Respository/Datasources/<Tableau Version>/<Locale>/`

<Note>
  See more information about Saved Data Sources in
  [Tableau Desktop Documentation](https://help.tableau.com/current/pro/desktop/en-us/export_connection.htm#save-a-data-source).
</Note>

#### Using a Local Data Source

1. Open Tableau Desktop
2. Choose the data source from **Saved Data Sources**
3. Provide your Honeydew credentials when instructed
4. Edit and save your workbook

#### Refreshing a Local Data Source

Changes in calculations reflect automatically and immediately in Tableau.

<Tip>
  Connect a Tableau to a development branch, and any logic changes in Honeydew will
  immediately reflect in your workbook.

  That allows for a quick experimentation workflow with Tableau on Honeydew semantics.
</Tip>

1. Download a data source from Honeydew to the same location in your Tableau repository
   (you may overwrite the previous version)
2. In a workbook based on the local data source, click **Data** → **New Data Source** and choose
   from saved data source the new version
3. Now you have two data sources: old and new. Click the old data source.
4. Click **Data** → **Replace Data Source** and switch the old to the new version.
5. Delete the old data source

### Using a Published Data Source from Tableau Cloud or Server

1. Open Tableau Desktop New Workbook
2. Choose **Search For Data** → **Tableau Server**
3. Connect with your Tableau Cloud credentials
4. Choose the published data source maintained by Honeydew and click **Connect**
5. Provide your Honeydew credentials when instructed

<Note>
  If the published data source has changed, click the data source → **Refresh** to see changes in a
  local workbook in Tableau Desktop connected to the published data source.
</Note>