Create a Virtual Connection

Applies to: Tableau Data Management

A virtual connection is a Tableau content type that provides a sharable central access point to data, and supports row-level security at the connection level. Creating a virtual connection is a multi-step process. This topic covers connecting to the data you want to share and working in the Tables tab of the virtual connection editor.

Connect to data

To create a virtual connection in Tableau Cloud or Tableau Server:

  1. From the Home or Explore page, click New > Virtual Connection.
  2. In the Connect to Data dialog box, select the connector for your data. For a list of supported connectors for virtual connections, see Creators: Connect to Data(Link opens in a new window) in the Tableau Desktop and Web Authoring help.
  3. Enter the information you're prompted for. The credentials you enter are saved in the virtual connection, so connection users don't have to enter credentials to connect to the data.
  4. Click Sign In if prompted. To add another connection, click The add a connection plus sign in the virtual connection editor and select a connector, enter credentials, and sign in.

A virtual connection can have multiple connections. Each connection accesses one database or file.

Note: For Tableau Cloud, virtual connections that connect to private network data use Tableau Bridge to keep data fresh. For information about configuring Tableau Bridge, see Configure and Manage the Bridge Client Pool(Link opens in a new window). For information about supported connections, see Connectivity with Bridge(Link opens in a new window).

Add another connection

As needed, add another connection to a virtual connection and connect to more than one database by clicking The add a connection plus sign in the virtual connection editor next to Connections. You can add a connection to a different server or database, or to the same server or database.

With multiple connections, you can:

  • Use a table from any connection or database as an entitlement table in a data policy that secures tables from other connections and databases.
  • Add or replace tables in a virtual connection with tables from a different database. For example, say you migrate data from one database to another. In the virtual connection editor, you can add a connection to the second database and replace the existing tables from the first database with tables from the second one.
  • Add multiple connections to the same server or database. This can be helpful when you need to for example access data from the same database but with different credentials.
  • Share a group of tables that are related or meant to be used together, no matter where they're physically located. For example, from multiple databases you can group tables related to employee information.

When you open a virtual connection to edit it, if prompted you must authenticate connections in sequence. If any connections fail to authenticate, you can't edit the virtual connection.

Select tables to include in the connection

If necessary, select a database to view the tables in it.

  1. On the left, under Tables, select the tables and click or drag them to the Tables tab on the right. You can include tables from different connections. Include an entitlement table, if you're using one.
  2. (Optional) Click New Custom SQL to create a custom table schema.

Note: Virtual connections don't support tables with a spatial data type.

Select live or extract mode for tables

You can set individual tables—whether they're from multiple connections or not—to either live or extract mode in the same virtual connection.

  • Live- Tables are queried directly from the database. (Live is the default.)
  • Extracts- Tables are extracted and saved to Tableau.

As an example, you can set some tables to extract mode so that they're not impacted by report generation or heavy customer traffic.

Under Tables, select the table or tables you want to change the mode for and select Actions, and Change to Live or Change to Extract. Alternatively, select the Actions Menu (...) in the table's row and select Live or Extract.

Incremental Extracts

Starting in Tableau Cloud June 2024 and Tableau Server 2024.2, you can configure table extracts for incremental refresh.

When configuring an incremental extract, you specify a key column that is used to identify new rows. When the incremental extract is refreshed, only the rows where the key column has increased will be added to the extract. Fewer rows processed means a faster extract refresh job and less load on the database.

For example, suppose we have an extract for the Batters table, and the data in the extract is:

Year Team
1978 Lions
1979 Tigers

The Batters table is configured for incremental extract refresh, and the key column is Year.

The live table is updated with a new row for 1980:

Year Team
1978 Lions
1979 Tigers
1980 Bears

When the Batters table's extract is refreshed incrementally, only rows that exceed the greatest value in the extract's key column are added. In this case, that means that the 1980 row is added to the extract. Instead of refreshing the entire extract file, only 1 row is processed and appended.

You can still do a full refresh on an extract configured for incremental refresh if you want to refresh the entire extract.

To configure incremental refresh for a table extract:

  1. Change the table from Live to Extract.
  2. Select the Actions Menu (...) in the table's row and select Extract Settings....
  3. Check Enable incremental refresh.
  4. Select an incrementing column to use when determining which rows to add.
  5. Select Save Settings.
    Extract settings dialog with incremental refresh enabled

Convert to Custom SQL

Starting in Tableau Cloud June 2024 and Tableau Server 2024.2, you can approximate the SQL used to connect to a table and use that as a starting point for your own custom SQL. Custom SQL allows you to filter or make other query changes that can modify the result set. Creating custom SQL this way instead of using New Custom SQL in the data pane is less impactful to existing virtual connections. Downstream assets see the table as the same table instead of a new one.

To convert a table to custom SQL:

  1. Select the Actions menu (...) in the row for the table.
  2. Select Convert to Custom SQL.
  3. In the Edit Custom SQL dialog, edit the SQL as needed.
  4. Select Generate Table.

Note: The SQL that first appears in the dialog should be considered a starting point, and may not work without modification. The virtual connection editor lacks nuanced information about the specific SQL syntax used in the connection. If you encounter errors when selecting the Generate Table button, try removing or changing single quotes, double quotes, back quotes, and square brackets to make the SQL compliant with the database you're using.

To edit the custom SQL:

  1. Select the Actions menu (...) in the row for the table.
  2. Select Edit Custom SQL.
  3. In the Edit Custom SQL dialog, edit the SQL.
  4. Select Generate Table.

To return the table to its default state, without custom SQL:

  1. Select the Actions menu (...) in the row for the table.
  2. Select Replace.
  3. In the replace table dialog, select the original table name.
  4. Select OK.

Extract table data

After a table or tables are changed from live to extract but haven’t been extracted yet, click Create Pending Extracts (or Run Pending Extracts in Tableau Server 2023.3 and earlier) to run the pending extracts. After all pending extracts are run, click Refresh All Extracts (or Run All Extracts in Tableau Server 2023.3 and earlier) to extract all table data at that time.

Alternatively, in Tableau Cloud June 2024 or Tableau Server 2024.2 and later, select the Actions Menu (...) in the table's row and select Refresh Extract.... If incremental refresh is not configured for the table, you can only select Refresh (Full). If incremental refresh is configured, you can choose either Refresh (Full) to refresh the extract completely, or Refresh (Incremental) to incrementally refresh the extract.

You must run any pending extracts before you publish the virtual connection. You can't edit the connection while extracts are generated.

Schedule extract refreshes of the tables in your virtual connection on the virtual connection page after you publish the connection. See Schedule Extract Refreshes for a Virtual Connection.

Set the table visibility state

Use the Visibility toggle on the Tables tab to show or hide tables and their data from users.

Check mark means show Users can see table data. You can create a data policy to govern which data users can see. (Visible is the default.)

X means hide Users can't see table data. You can use hidden tables in a data policy and as an entitlement table.

See table details

Click a table at the top of the Tables tab to see its details. You can make simple edits in the Table Details section, such as change a table name, hide or rename a column, or change a data type.

Switch the table information you see using these icons:

Tag icon represents column data type. A list of columns in the table and each column's data type.
Table icon represents column sample data. Sample data for each column and linked keys, if available. Linked keys show which columns link to other tables. They're visible only when databases have primary and foreign key information.
Profile icon represents the column value range. The range of values in a histogram for each column selected.

Refresh data from the database

Click the refresh icon The refresh icon on the virtual connection editor toolbar in the toolbar to get the latest data from the database for all the connections in a virtual connection, including:

  • The lists of databases, tables, and columns. Both the tables included in a virtual connection and not included are refreshed.
  • Table and histogram data.

For tables in live mode, refreshing retrieves the latest list of databases, tables, and columns and the most recent table and histogram data. For tables in extract mode, refreshing retrieves the updated list of tables and columns. But to see the most recent table and histogram data, you must start a new extract. For example, when there's a new column in a database table and you click the refresh icon, the new column appears in the editor but its data does not. To see the most current data, you must start a new extract.

Refreshing data invalidates any currently cached data. Closing and reopening the editor, switching tables from extract to live mode, and changing a connection credential like username or password also refreshes data.

Who can do this

To create a virtual connection, you must

  • have credentials to the database that the virtual connection connects to, and
  • be a server or site administrator, or a Creator.

Next steps

After tables have been added and configured on the Tables tab, you can choose to Create a Data Policy for Row-Level Security or Publish a Virtual Connection and Set Permissions.

See also

Use a .properties file to customize a JDBC connection — If you're customizing a JDBC-based connection, you can also make customizations in a .properties file

Back to top
Thanks for your feedback!Your feedback has been successfully submitted. Thank you!