Was this page helpful?
Yes No
Have a comment? Please leave it here.Thanks for your feedback!

Home > 

Connect to and Prepare Data > Set Up Data Sources > Connect to a Custom SQL Query

Connect to a Custom SQL Query


In this topic:


For most databases, you can connect to a specific query rather than the entire data set. Because databases have slightly different SQL syntax from each other, the custom SQL you might use to connect to one database might be different from the custom SQL you might use to connect to another. However, using custom SQL can be useful when you know exactly the information you need and understand how to write SQL queries.

Though there are several common uses for custom SQL, you might use custom SQL to union your data across tables, recast fields to perform cross-database joins, restructure or reduce the size of your data for analysis, etc.

Note: For Excel and text file data sources, this option is available only in workbooks that were created before Tableau Desktop 8.2 or when using Tableau Desktop on Windows with the legacy connection. To connect to Excel or text files using the legacy connection, connect to the file, and in the Open dialog box, click the Open drop-down menu, and then select Open with Legacy Connection.

Connect to a custom SQL query

  1. After connecting to your data, double-click the New Custom SQL option on the Data Source page.

  2. Type or paste the query into the text box.

  3. When finished, click OK.

When you finish making the connection to your data, only relevant fields display in the data grid of the Data Source page.

Examples of custom SQL queries

Combine your tables vertically (union)

If you need to append data to each other, you can use the union option directly in Tableau. In some cases your database does not support this option, so you can use custom SQL instead.

For example, suppose you have the following two tables: November and December.

November December

You can use the following custom SQL query to append the second table, December, to the first table, November:

SELECT * FROM November UNION ALL SELECT * FROM December

The result of the query looks like this in the data grid:

For more information about the union option, see Union Your Data.

Change data type of a field to do a cross-database join

When you want to perform a join between two tables, the data type of the fields you join on must be the same. In cases when the data type of the fields are not the same, you can use custom SQL to change the data type (cast) the field before performing the join.

For example, suppose you want to join two tables, Main and Sub, using the Root and ID fields, respectively. The Root field is a number type and the ID field is a string type. You can use the following custom SQL to change the data type of Root from a number to a string so that you can join the Main and Sub tables using the Root and ID fields.

SELECT [Main].[Root] AS [Root_Number]
CAST([Main].[Root] AS INT] AS [Root_String]
FROM [Main]

The result of this query shows the original Root field and the Root field cast as a string.

For more information about joins and cross-database joins, see Join Your Data.

Reduce the size of your data

When working with very large data sets, sometimes you can save time while working with your data if you reduce its size first.

For example, suppose you have a large table called summary_tests. You can use the following custom SQL query to retrieve the specified columns and records thereby reducing the size of the data set that you connect to from Tableau.

SELECT [tests_allup].[id] AS [ID],[tests_allup].[version] AS [Version],[tests_allup].[type] AS [Type]
FROM [tests_allup]
WHERE [tests_allup].[version] >=9.0.0
GROUPBY [tests_allup].[id]

Restructure your data (pivot)

In some cases, you might be working with a table that needs to be restructured before analysis. Though this type of task can be done directly in Tableau by using options like pivot, your database might not support it. In this case, you can use custom SQL instead.

For example, suppose you have the following table:

To change its structure and optimize your data for analysis in Tableau, you can use the following custom SQL query:

SELECT Table1.Season ID AS [Season ID],
Table1.Items - Don't like AS [Quantity],
"Don't Like" AS [Reason]
FROM Table1
UNION ALL
SELECT Table1.Season ID AS [Season ID],
Table.Items - Defective AS [Quantity],
"Defective" AS [Reason]
FROM Table1
UNION ALL
SELECT Table1.Season ID AS [Season ID],
Table1.Items - Too big AS [Quantity],
"Too Big" AS [Reason]
FROM Table1
UNION ALL
SELECT Table1.Season ID AS Season ID,
Table1.Items - Too small AS [Quantity]
"Too Small" AS [Reason]
FROM Table1

The result of the query looks like this in the data grid:

For more information about the pivot option, see Pivot Data from Columns to Rows.

Combine (join) and aggregate your data

If you need to combine tables and aggregate your data, you can use both a join and default aggregation type options directly in Tableau. In some cases you might need to use custom SQL instead.

For example, suppose you have the following two tables: Orders and Vendors.

Orders Vendors

You can use the following custom SQL query to find a count on the number of orders and do a left join on the Orders and Vendors tables:

SELECT Vendors.Name,COUNT(Orders.Order) AS Number Of Orders
FROM Orders
LEFT JOIN Vendors
ON Orders.VendorID=Vendors.VendorID
GROUP BY Name;

The result of the query looks like this:

For more information about joins, see Join Your Data.

Errors when duplicate columns are referenced

If your custom SQL query references duplicate columns, you may get errors when trying to use one of the columns in your analysis in Tableau. This will happen even if the query is valid. For example, consider the following query:

SELECT * FROM authors, titleauthor WHERE authors.au_id = titleauthor.au_id

The query is valid, but the au_id field is ambiguous because it exists in both the “authors” table and the “titleauthor” table. Tableau will connect to the query but you will get an error anytime you try to use the au_id field. This is because Tableau doesn’t know which table you are referring to.

Edit a custom SQL query

To edit a custom SQL query

  1. On the data source page, in the canvas, hover over the custom SQL table until the edit button displays.

  2. In the dialog box, edit the custom SQL query.

Use parameters in a custom SQL query

You can use parameters in a custom SQL query statement to replace a constant value with a dynamic value. You can then update the parameter in the workbook to modify the connection. For example, you may connect to a custom SQL query that provides web traffic data for a particular page that is specified by a pageID. Instead of using a constant value for the pageID value in the SQL query, you can insert a parameter. Then after finishing the connection, you can show a parameter control in the workbook. Use the parameter control to switch out the pageID and pull in data for each page of interest without having to edit or duplicate the connection.

You can create a parameter directly from the Custom SQL dialog box or use any parameters that are part of the workbook. If you create a new parameter, it becomes available for use in the workbook just like any other parameter. See Parameters to learn more.

To add a parameter to a custom SQL query

  1. On the data source page, in the canvas, hover over the table until the edit icon displays, and then click the edit button.

  2. At the bottom of the dialog box, click Insert Parameter.

  3. Select a constant value in the SQL statement and then, from the Insert Parameter drop-down menu select the parameter you want to use instead. If you have not created a parameter yet, select Create a new parameter. Follow the instructions in Creating Parameters to create a parameter.

Note: Parameters can only replace literal values. They cannot replace expressions or identifiers such as table names.

In the example below, the custom SQL query returns all orders that are marked as Urgent priority. In the custom SQL statement, the order priority is the constant value. If you want to change the connection to see the High priority orders, you would have to edit the data source.

Instead of creating and maintaining many variations of the same query, you can replace the constant order priority value with a parameter. The parameter should contain all of the possible values for Order Priority.

After you create a parameter, you can insert it into the SQL statement to replace the constant value.

After you finish editing the connection, the new parameter is listed in the Parameters area at the bottom of the Data pane and the parameter control displays on the right side of the view. As you select different values, the connection updates.

Note: If you are using an extract, you must refresh the extract in order to reflect changes to the parameter. Publishing a data source that uses Custom SQL parameters includes the parameters. The parameters are transferred to any workbooks that connect to the data source.