Custom SQL Support in Tableau Through BI Connector

Modified on Fri, 27 Feb at 5:25 AM

Overview

This document describes how BI Connector supports Tableau’s Custom SQL feature, enabling users to write their own Oracle subject area queries directly from within Tableau.

User relevance for this documentation

This documentation is relevant for Tableau Developer users who are well-versed with writing custom SQL statements to Oracle Subject Areas.

If you are not familiar with writing SQL to Oracle Subject Areas, or if you’re not aware how the Subject Area tables are joined under the hood, we recommend creating an Analysis report instead with the view you want, and connecting to that report using the BI Connector.

What Is Custom SQL?

Custom SQL in Tableau allows users to define a data connection to an ODBC source using a simple SQL SELECT statement. Instead of selecting tables from the Data Source pane, the user writes a query directly, giving them full control over which data is fetched from the source.

When connected via BI Connector, Tableau shows a ‘New Custom SQL’ option on the Data Source page. Selecting this opens an editor where users can write Oracle-compatible queries against the subject areas.

How Tableau’s ODBC Custom SQL Benefits Tableau Developer Users?

In the standard Tableau flow, one schema (subject area) can be selected at a time, and only the tables within that schema can be dragged and dropped onto the canvas. Combining data from two separate subject areas in a single connection is not possible through this built-in interface.

Custom SQL removes this restriction. It allows users to perform advanced operations that were not possible through Tableau’s existing drag-and-drop flow, including:

Combining two or more subject areas in a single query using JOIN or UNION ALL which cannot be done through the standard Tableau interface.
Selecting only the specific columns and rows needed, reducing data transfer and improving workbook performance.
Pushing aggregations (SUM, COUNT, GROUP BY) to the Oracle layer before data reaches Tableau, enabling faster dashboards on large datasets.
Applying WHERE filters at the source so only relevant data is returned to Tableau, rather than applying filters after the entire dataset is returned.

How to Use Custom SQL via BI Connector

Follow the steps below to connect Tableau to Oracle subject areas using Custom SQL:

Step 1 : Open Tableau and Select BI Connector

Launch Tableau Desktop. On the Connect pane, look for ‘BI Connector by Guidanz Inc’ under Installed Connectors. If it does not appear in the installed list, use the search box at the top : it will appear under Additional Connectors. Double-click it to install.

Step 2 : Enter Connection Details

After selecting BI Connector, a sign-in dialog appears. Enter your DSN, Username, and Password, then click Sign In.

Step 3 : Select the Database

Once signed in, you will be taken to the Data Source page. Under the Database dropdown, select the Oracle Fusion URL for your environment.

Step 4 : Select the Schema

After selecting the database, the Schema dropdown will appear. Choose a subject area to connect to. Note: that this selection does not restrict your Custom SQL query, which can reference any subject area

Step 5 : Open the Custom SQL Editor

Once the schema is selected, ‘New Custom SQL’ will appear in the left panel below the table search. Double-click it to open the query editor.

Step 6 : Write Your Query

The ‘Edit Custom SQL’ dialog opens. Type or paste your Oracle SELECT statement. You can query any subject area from here : you are not limited to the schema selected in the left panel. The query must be a single SELECT statement.

Step 7 : Preview the Data

Click ‘Preview Results’ to verify the query returns the expected columns and rows before applying it.

Step 8 : Confirm and Choose Connection Mode

Click OK to confirm. Tableau loads the query result as a virtual table. Choose Live or Extract mode to load the data into your workbook.

Troubleshooting

If your Custom SQL query produces an error in Tableau, verify the query directly in Oracle BI using the Issue SQL interface. If the query runs successfully there, it will work in Tableau via BI Connector as well. This diagnostic step helps quickly determine whether the issue is with the query itself or in the connection.

Publishing to Tableau Cloud

To publish a workbook or data source using BI Connector Custom SQL to Tableau Cloud, you must use Tableau Bridge. Follow the steps below:

Step 1 : Download the BI Connector TACO File

Download the BI Connector connector file (.taco) from the Tableau Exchange:

https://exchange.tableau.com/en-GB/products/282

Step 2 : Install the TACO File

Once downloaded, place the .taco file in the following folder on the machine running Tableau Bridge:

C:\Users\<username or machine name>\Documents\My Tableau Bridge Repository\Connectors

Step 3 : Restart Tableau Bridge

After placing the file in the Connectors folder, restart Tableau Bridge. The connector will be picked up automatically on restart and the connection will be available for published workbooks.

Important Limitations

Please review the following limitations before publishing or distributing workbooks that use Custom SQL via BI Connector.

ODBC Default Does Not Support Custom SQL

Custom SQL is only supported through BI Connector, not through a generic ODBC connection. Ensure you are using the “BI Connector by Guidanz” connector specifically when working with Custom SQL.

Separate Publishing Required

For ODBC based sources, Tableau supports publishing the Tableau workbook and data source separately. Embedded data sources published together within a workbook are not supported. Always publish the data source independently first, then publish the workbook.