When to Use Custom SQL in Tableau?

Tableau's drag-and-drop interface is fantastic for quickly exploring data, but sometimes you need more direct control over how that data is pulled and prepared. This is where Custom SQL comes in, acting as an escape hatch that gives you power over the data connection itself. This article will walk you through the specific scenarios where using a Custom SQL query is the right move - and when it's best to stick with Tableau's standard visual tools.

Graphed

Build AI Agents for Marketing

Build virtual employees that run your go to market. Connect your data sources, deploy autonomous agents, and grow your company.

Build Your First Agent

What Exactly is a Custom SQL Query in Tableau?

Typically, when you drag tables onto the Tableau data source canvas and create joins, Tableau automatically writes a Structured Query Language (SQL) query behind the scenes. It generates the code to fetch exactly what you’ve visually requested. A Custom SQL query, on the other hand, allows you to bypass that process and write your own SQL code from scratch.

Instead of connecting to a whole table (or multiple tables), you connect to the results of your query. This means you can shape, filter, aggregate, and transform your data at the source - before it ever even loads into Tableau. It's a way of telling your database, "Don't just give me the raw data, give it to me exactly like this."

Key Scenarios for Using Custom SQL in Tableau

Writing your own SQL query isn’t always necessary, but in certain situations, it can save you an enormous amount of time and solve problems that are otherwise difficult or even impossible to handle within Tableau's interface. Here are the most common reasons to use it.

AI Agents for Marketing

Crash Course

Graphed

Free PDF · the crash course

AI Agents for Marketing Crash Course

Learn how to deploy AI marketing agents across your go-to-market — the best tools, prompts, and workflows to turn your data into autonomous execution without writing code.

Download the PDF

1. To Improve Performance with Pre-Aggregation

Imagine your sales table has millions of raw transaction records, one for every single item sold. If you only need to build a dashboard showing total sales per day, loading all those individual rows into Tableau is incredibly inefficient. Your dashboard will be slow to load, slow to refresh, and slow to respond to filters.

With Custom SQL, you can aggregate the data at the source. Instead of pulling millions of rows, you can pull only the summarized results.

For example, a query like this could be your data source:

SELECT
  transaction_date,
  product_category,
  SUM(sales_amount) as total_sales,
  COUNT(order_id) as number_of_orders
FROM
  sales_transactions
GROUP BY
  transaction_date,
  product_category

Now, Tableau is only working with the summarized data (one row per date and category), which is a much smaller and faster dataset. This can dramatically speed up your dashboards.

2. To Handle Complex Joins or Data Unions

Tableau’s visual join interface is great for standard joins (inner, left, right, full outer) based on matching key fields. But what if you need to join tables on more complex logic?

• Non-Equi Joins: What if you need to join a sales table to a promotions table based on a date range (e.g., sales.date BETWEEN promo.start_date AND promo.end_date)? Tableau’s visual tool can struggle with this type of "greater than/less than" logic.
• Joins with Calculations: Sometimes you need to join based on a calculated field, like joining on the first five characters of a postcode (LEFT(sales.zipcode, 5) = stores.zipcode_prefix) or a modified date function.

Custom SQL gives you the full power of SQL's JOIN clause to write this logic explicitly. Similarly, if you want to stack data from tables with slightly different structures, complex UNION statements with data type casting (CAST) or conditional logic (CASE) can be much cleaner to write directly in SQL.

3. For Advanced Data Reshaping (Pivoting/Unpivoting)

Data is often stored in a "wide" format that isn’t ideal for analysis in Tableau. For instance, you might have survey results with each question as its own column, or sales data with a separate column for each month (Jan_Sales, Feb_Sales, etc.).

Tableau needs this data in a relational, "tall" format (e.g., one column for "Month" and one column for "Sales").

While Tableau has a built-in Pivot feature on the data source page, it can be limited. A Custom SQL query using multiple UNION ALL statements is a classic and powerful way to unpivot wide data into a tall, analysis-ready format. This gives you more control over column naming and data handling than the built-in tool.

Here's a simplified example of unpivoting monthly columns:

SELECT
  product_id, 'January' as month, Q1_Sales as sales
  FROM sales_by_quarter_wide
UNION ALL
SELECT
  product_id, 'February' as month, Q2_Sales as sales
  FROM sales_by_quarter_wide
UNION ALL
SELECT
  product_id, 'March' as month, Q3_Sales as sales
  FROM sales_by_quarter_wide

Graphed

Build AI Agents for Marketing

Build virtual employees that run your go to market. Connect your data sources, deploy autonomous agents, and grow your company.

Build Your First Agent

4. To Leverage Database-Specific Features

Your database might have specialized functions or features that Tableau doesn't support natively. This could include powerful window functions for ranking (like PARTITION BY), advanced spatial functions for mapping analysis, or proprietary functions for data formatting or calculations.

By using Custom SQL, you can run queries that harness the full power of your source database. You can execute complex scripts, pass parameters to database functions, or even run stored procedures (on supported databases) simply by writing the appropriate call in your Custom SQL query window.

How to Use Custom SQL in Tableau: A Quick Walkthrough

Adding a Custom SQL query is straightforward. Once you’ve connected to your data source (like SQL Server, PostgreSQL, etc.):

1. On the Data Source page, look in the left pane under "Connections."
2. Drag the "New Custom SQL" option onto the canvas area where you normally see your tables.
3. An "Edit Custom SQL" dialog box will appear. Here, you can type or paste your SQL query.
4. Click "OK". Tableau will execute the query and show you a preview of the results.

From this point forward, Tableau will treat the results of your query as if it were a single, flat table. You can then join this Custom SQL "table" to other tables if needed.

A Word of Caution: When to Avoid Custom SQL

With great power comes great responsibility. Using Custom SQL isn’t a magic bullet and can sometimes cause more problems than it solves.

AI Agents for Marketing

Crash Course

Graphed

Free PDF · the crash course

AI Agents for Marketing Crash Course

Learn how to deploy AI marketing agents across your go-to-market — the best tools, prompts, and workflows to turn your data into autonomous execution without writing code.

Download the PDF

1. You might hinder Tableau's built-in performance optimizations.

When you use the standard drag-and-drop interface, Tableau has the freedom to optimize the queries it sends to your database. It can sometimes simplify queries, limit fields being retrieved (query culling), or adjust joins on the fly. When you provide a Custom SQL query, Tableau must treat it as a single block of code and execute it exactly as written. This can sometimes lead to worse performance if your handwritten SQL is not well-optimized.

General Rule: If you can accomplish your goal easily with Tableau's standard data modeling features, do that first. Save Custom SQL for when those features hit a wall.

2. It creates maintenance overhead and can be a "black box."

A Custom SQL data source can be difficult for other people on your team to understand and maintain. Someone opening your workbook who doesn't know SQL will have no visibility into how the data is being transformed, joined, or filtered. Documenting your query is essential if you want your workbook to be maintainable in the long term.

Final Thoughts

Custom SQL in Tableau is a powerful feature for situations where you need precise control over your query. It's the perfect solution for performance tuning through pre-aggregation, handling complex joins, reshaping messy data, and leveraging unique database functions. However, always weigh its power against the potential drawbacks in performance and maintainability.

Mastering tools like Tableau and SQL is a great way to manage complex data challenges. As we developed Graphed , we saw how often marketers and founders get stuck on the technical side of things when all they really want are answers. Instead of writing SQL or learning a complex BI tool, our approach lets you describe the charts or reports you need in plain English - "show me total sales by country for the last quarter as a bar chart" - and the system builds it for you automatically. We handle connecting to your sources and building the live dashboard so you can skip straight to the insights.