How to Use Custom SQL Queries in Tableau

Using Custom SQL in Tableau gives you direct control over the data you bring in for analysis, letting you craft the perfect dataset before it even touches a worksheet. While Tableau’s visual data model is powerful, sometimes you need to write a specific query to pre-aggregate, pivot, or filter data right at the source. This article walks you through exactly how to set up and use Custom SQL in Tableau, when it makes sense to use it, and some best practices to avoid common pitfalls.

Graphed

Your AI Data Analyst to Create Live Dashboards

Connect your data sources and let AI build beautiful, real-time dashboards for you in seconds.

Build Your First Dashboard

What Exactly is Custom SQL in Tableau?

Normally, when you connect to a database in Tableau, you see a list of tables, and you can drag and drop them onto the canvas. Tableau's relationship model (the "noodles") intelligently figures out what SQL queries to generate behind the scenes based on the fields you use in your visualizations. This process is dynamic and highly optimized.

Custom SQL is an alternative to this. Instead of dragging tables, you write your own SQL statement (SELECT, FROM, JOIN, WHERE, etc.). Tableau then treats the result of your single query as a single, monolithic table. It essentially wraps your code in a subquery like this: SELECT * FROM (<em>Your Custom SQL Here</em>) AS CustomSQLQuery.

You’re telling Tableau, “Don’t worry about generating the main query, I’ve already handled it. Just use these results.”

AI for Data Analysis

Crash Course

Graphed

Free PDF Guide

AI for Data Analysis Crash Course

Learn how to get AI to do data analysis for you — the best tools, prompts, and workflows to go from raw data to insights without writing a single line of code.

Download Free Guide

Why Would You Use Custom SQL?

Writing your own query might seem like extra work, so why do it? There are several strategic reasons:

• Data Shaping at the Source: Sometimes, the data isn't in a clean, reporting-friendly format. You can use Custom SQL to handle tasks like unpivoting data, combining fields with complex logic (e.g., using CASE statements), or performing specific type casting that’s easier in SQL than in Tableau.
• Improved Performance (With a Catch): By filtering and aggregating data at the database level, you significantly reduce the amount of data transferred to Tableau. For instance, if you only need sales totals by day, you can pre-aggregate billions of raw transaction rows into thousands of summary rows, making your dashboard much faster. The catch is that a poorly written query can harm performance, which we'll cover later.
• Executing Stored Procedures: Some databases have stored procedures that contain complex business logic to fetch data. Custom SQL is the primary way to call these procedures and bring their results into Tableau.
• Connecting to Legacy or Specific Views: In some organizations, data analysts are required to use specific, approved database views or queries for governance and consistency. Custom SQL allows you to plug these certified queries directly into Tableau.
• Using Database-Specific Functions: Every database has its own unique functions that Tableau might not natively support or generate. Custom SQL lets you leverage these proprietary functions for specialized calculations or data manipulation.

A Step-by-Step Guide to Using Custom SQL in Tableau

Ready to write your first query? The process is straightforward once you know where to look. Let's walk through it with a hypothetical e-commerce database containing customers, orders, and products.

Step 1: Connect to Your Database

Start by opening Tableau and connecting to your SQL-based data source (like PostgreSQL, SQL Server, MySQL, Oracle, etc.). Once you’ve entered your credentials, you’ll be on the Data Source page.

Step 2: Locate the 'New Custom SQL' Option

On the left-hand side of the Data Source page, you'll see a list of tables in your database. Instead of dragging one of those tables, look for an option called New Custom SQL. Drag it onto the canvas, just as you would with a table.

Step 3: Write and Edit Your SQL Query

Dragging "New Custom SQL" will open a dialog box. This is where you'll write or paste your SQL code. For our example, let’s join a few tables to get a list of orders with customer and product details, but only for orders from the year 2023.

Here’s the sample query we’ll use:

SELECT
  o.OrderID,
  o.OrderDate,
  c.CustomerName,
  c.Region,
  p.ProductName,
  p.Category,
  oi.Sales,
  oi.Quantity
FROM Orders AS o
JOIN Customers AS c ON o.CustomerID = c.CustomerID
JOIN OrderDetails AS oi ON o.OrderID = oi.OrderID
JOIN Products AS p ON oi.ProductID = p.ProductID
WHERE o.OrderDate >= '2023-01-01'

Graphed

Your AI Data Analyst to Create Live Dashboards

Connect your data sources and let AI build beautiful, real-time dashboards for you in seconds.

Build Your First Dashboard

Step 4: Preview and Confirm

Before closing the dialog box, click the Preview Results button. This asks Tableau to execute the query against your database and show you the first hundred or so rows. It’s an essential step for catching syntax errors or logic mistakes early on. If everything looks correct, click OK.

Step 5: Start Visualizing

After you click OK, the Custom SQL query will appear as a single table-like object in your data canvas. You can now go to a worksheet and start building visualizations with the fields from your query, just as you would with any other data source.

Making Your Custom SQL Interactive with Parameters

One major drawback of a static Custom SQL query is that it's, well, static. If a user wants to select a different date range, they can't unless you build that flexibility into the query itself. This is where Tableau Parameters come in.

Parameters are dynamic values that can be changed by dashboard users and inserted into calculations, filters, and even your Custom SQL. Let's replace our hardcoded '2023-01-01' date with a dynamic parameter.

1. Create a Parameter: In any worksheet view (or on the data source page), click the dropdown arrow in the Data pane and select Create Parameter. Let's name it 'Start Date', set the Data type to 'Date', and give it a current value.
2. Edit Your Custom SQL: Go back to your Data Source page, click the dropdown on your Custom SQL object, and select Edit Custom SQL.
3. Insert the Parameter: Erase the hardcoded date '2023-01-01'. Now, instead of typing, click the Insert Parameter button in the dialog and select the 'Start Date' parameter you just created.

Your WHERE clause will now look like this:

WHERE o.OrderDate >= [Parameters].[Start Date]

Now, if you show this parameter control on your dashboard, your users can pick a date. Each time they select a new date, Tableau re-runs your query with the updated value, making your visualization interactive again.

AI for Data Analysis

Crash Course

Graphed

Free PDF Guide

AI for Data Analysis Crash Course

Learn how to get AI to do data analysis for you — the best tools, prompts, and workflows to go from raw data to insights without writing a single line of code.

Download Free Guide

Best Practices and Common Pitfalls

Custom SQL is a powerful feature, but it needs to be used thoughtfully. Here are some guidelines to keep in mind.

When to Use Custom SQL:

• When you need to pre-aggregate massive tables into a smaller summary table.
• For complex unions or joins that are hard to model in Tableau’s graphical interface.
• To call a database stored procedure.
• When you must use non-standard, database-specific functions.

When to Avoid Custom SQL:

• It's a "Performance Black Box": Normally, Tableau analyzes your visualization to create the most efficient query possible, a technique called "query optimization". For example, it might skip joining a table if none of its fields are used in the viz. With Custom SQL, Tableau loses this ability because your query is a big, unchangeable block. It has to run the entire query every single time, which can sometimes slow things down.
• Maintenance is More Difficult: Raw SQL is more brittle than Tableau's relationship model. If a column name changes in the database, your whole query breaks. With the standard approach, Tableau can often adapt to schema changes more gracefully.
• For Simple Filters and Joins: If all you need is a simple join and a WHERE clause, always try to use Tableau’s native data connection features first. They are often more performant and easier to manage.

Tips for Writing Good Custom SQL

• Don’t use SELECT *. Always explicitly list out the exact columns you need. Pulling unnecessary columns adds overhead to both the database and Tableau.
• Filter Aggressively: The main performance benefit of Custom SQL comes from reducing the size of the data. Use your WHERE clause to bring in only the records you truly require for your analysis.
• Test Outside Tableau First: Use a native SQL client like Dbeaver or SSMS to write and test your query. These tools give you better error feedback and let you confirm your logic before you even open Tableau.
• Use Aliases: Use table aliases (e.g., FROM Orders AS o) and column aliases (SELECT CustomerName AS "Customer Name") to keep your code clean and your field names user-friendly.

Final Thoughts

Using Custom SQL in Tableau is a fantastic tool to have in your toolbox, allowing you to fine-tune your data extraction for performance, clarity, and specific business logic. It provides deep control but comes with the responsibility of writing efficient, maintainable code. For the right situations - like pre-aggregating data or calling stored procedures - it can be the perfect solution.

For many teams, the need to write and maintain SQL can become a significant bottleneck, delaying reports and tying up valuable analyst time. That’s why we built Graphed, an AI data analyst that streamlines this exact process. You connect your data sources in seconds, then create dashboards and reports just by describing what you want to see in plain English. There’s no SQL to write or BI tool to learn. You get the same power of a custom query but with the simplicity of asking a question, bridging the gap between raw data and actionable insight.