How to Edit Custom SQL in Tableau

When Tableau’s drag-and-drop interface isn’t enough to shape your data exactly how you need it, Custom SQL becomes your best friend. Maybe you need to pre-aggregate data, perform a complex join, or stack tables together before you even start visualizing. This guide will walk you through exactly how to create, edit, and manage Custom SQL queries inside a Tableau workbook.

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

What is Custom SQL in Tableau and When Should You Use It?

In Tableau, the Custom SQL feature allows you to write your own SQL statement to define your data source. Instead of dragging individual tables onto the canvas and letting Tableau build the joins, you provide the precise query that retrieves the data you want. This gives you granular control over the data structure before it enters the Tableau environment.

While Tableau's relational model is incredible for most situations, there are specific scenarios where writing your own SQL is either more efficient or downright necessary:

• Pre-aggregating Data: If you're working with billions of rows, pulling every single record into Tableau can be incredibly slow. You can use a GROUP BY clause in your Custom SQL to sum, count, or average data at the database level, sending a much smaller, pre-aggregated dataset to Tableau.
• Complex Joins: Tableau’s visual joins are great for standard INNER and LEFT joins on one or two keys. But what if you need to join on a condition, like TableA.date > TableB.date, or use a FULL OUTER join that isn't visually supported? Custom SQL lets you write any join logic your database supports.
• Unions and Data Stacking: Sometimes your data is split across multiple tables with the same structure (e.g., sales data for 2021, 2022, and 2023 are in separate tables). You can use UNION ALL in Custom SQL to stack this data into a single table. While Tableau has its own Union feature, performing it in SQL can sometimes be clearer or more performant.
• Data Reshaping: You might need to pivot or unpivot data and transform it in ways that are difficult to do visually. SQL’s CASE statements and other functions provide immense flexibility here.
• Filtering at the Source: With a Custom SQL query, you can add a WHERE clause to filter out irrelevant data at the database level. This makes workbooks much faster.
• Leveraging Database Functions: Your specific database (like PostgreSQL, SQL Server, or Oracle) has its own unique set of functions for tasks like date manipulation or statistical analysis. Custom SQL lets you use these powerful, native functions directly.

How to Create a Custom SQL Data Source

Before you can edit a query, you first need to create one. The process is straightforward and happens on the Data Source page.

Step 1: Connect to Your Data

Open Tableau and in the "Connect" pane, select the database you want to query (e.g., Microsoft SQL Server, PostgreSQL, MySQL). Enter your server credentials and sign in.

Step 2: Select "New Custom SQL"

Once you've selected your database, Tableau will navigate you to the Data Source page. In the left-hand pane where your tables are listed, you should see an option labeled New Custom SQL. Drag it onto the canvas, just as you would with a regular table.

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

Step 3: Write Your Query

A dialog box will appear, ready for your SQL code. Here you can either type your query from scratch or paste in one you've already prepared. For now, let’s start with something simple.

SELECT
  order_id,
  order_date,
  customer_id,
  category,
  sales
FROM public.orders
WHERE region = 'West',

Step 4: Preview and Use

Click OK. Tableau will run a preview of the query against your database and show the results in the data grid below. If everything looks correct, you now have a data source based entirely on your query. From here, you can click over to a worksheet and start building visualizations.

How to Edit an Existing Custom SQL Query

Projects change. You might need to add a new field, adjust a filter, or change the join logic. Thankfully, editing a Custom SQL query is just as easy as creating one.

Step 1: Navigate Back to the Data Source page

At the bottom of your Tableau workbook, click the Data Source tab to return to the area where you manage your connections.

Step 2: Find Your Custom SQL Connection

On the canvas, your Custom SQL query appears as a single rectangle—almost like a database view—with a specific icon (often an orange box or query icon) and the default name "Custom SQL Query".

Step 3: Open the Edit Menu

Hover your mouse over the Custom SQL object. A small dropdown arrow will appear on the top right. Click it, and from the menu, select Edit Custom SQL Query.

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

Step 4: Modify Your Query

The same dialog box where you wrote the initial query will reappear, populated with your existing code. You can now make any changes you need.

Let's say a stakeholder asks you to include the "Central" region in your analysis in addition to the "West." All you need to do is modify the WHERE clause.

Before:

SELECT
  order_id,
  order_date,
  customer_id,
  category,
  sales
FROM public.orders
WHERE region = 'West',

After:

SELECT
  order_id,
  order_date,
  customer_id,
  category,
  sales
FROM public.orders
WHERE region IN ('West', 'Central'),

Once you click OK, Tableau will rerun the updated query and refresh the data preview. Your worksheets will update automatically to reflect the newly included data.

Best Practices for Working with Custom SQL in Tableau

Custom SQL is powerful, but it's important to use it wisely to avoid creating slow or unmanageable workbooks. Here are a few tips to keep in mind.

Use Parameters for Dynamic Queries

Hard-coding filters in your SQL is fine for static reports, but what if you want to give your users control? You can insert a Tableau Parameter directly into your SQL code. This lets end-users change the value of a filter through a dropdown or text box in the dashboard itself.

For example, instead of WHERE region = 'West', you could create a "RegionParameter" in Tableau and a calculated field, then reference the parameter in your query:

SELECT
  order_id,
  order_date,
  customer_id,
  category,
  sales
FROM public.orders
WHERE region = <Parameters.RegionParameter>

Prioritize Performance

A misconception is that Custom SQL is always faster. That's not always true. When you drag and drop tables, Tableau works behind the scenes to optimize the queries it sends to your database (a process called "query folding"). A poorly written Custom SQL query can perform much worse than what Tableau creates automatically.

Use Custom SQL when:

• You are significantly reducing the amount of data being pulled (e.g., heavy pre-aggregation or filtering).
• You need functions or joins Tableau's relationship model doesn't support.

Be cautious with Custom SQL when:

• You are performing simple joins that Tableau could optimize itself.

Always test the performance of your dashboard before and after implementing a complex Custom SQL connection.

Graphed

Still Building Reports Manually?

Watch how growth teams are getting answers in seconds — not days.

Watch the Demo

Keep Your Code Clean

Your future self (and your teammates) will thank you. Treat the Custom SQL editor like any code editor.

• Use line breaks and indentation to make the query readable.
• Add comments (-- comment here) to explain complex logic or the purpose of a section of code.
• Give your columns clear, descriptive aliases using AS. For example, SUM(sales) AS total_revenue.

Test Your Query Externally

The Custom SQL editor in Tableau is functional but very basic. It lacks helpful features and debugging capabilities that dedicated SQL tools (like DBeaver, SQL Server Management Studio, or Postico) provide.

For any query more than a few lines long, it's a good practice to write and test it in your preferred SQL client first. Once it runs correctly and returns the data you expect, you can simply copy and paste it into Tableau’s editor.

Final Thoughts

Editing Custom SQL in Tableau is a key skill that unlocks a new level of control over your data preparation. It allows you to tackle complex data challenges that go beyond simple joins and filters, ensuring your visualizations are built on a solid and efficient data foundation.

We know that managing SQL queries, debugging connections, and manually piecing together reports is often a time-consuming part of the analytics process. We built Graphed to simplify this entire workflow— it connects directly to your data sources and enables you to create live dashboards and analytics by just describing what you need in plain English. Instead of tweaking SQL, you work with your data conversationally and let our AI handle the rest.