How to Check Custom SQL Query in Tableau

Using custom SQL in Tableau gives you incredible power to shape your data before it even hits your dashboard. But if your query has a mistake, Tableau can be less than helpful, often showing a generic error message that leaves you guessing. This guide will walk you through exactly how to write, check, and troubleshoot your custom SQL queries directly within Tableau so you can get the data you need, error-free.

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 is Custom SQL in Tableau and Why Use It?

Normally when you connect to data in Tableau, you visually join tables using relationships or joins - dragging and dropping tables onto a canvas. Custom SQL is a way to bypass that interface and write your own SQL query to pull data from your database (like PostgreSQL, MySQL, SQL Server, etc.).

This approach gives you a lot more control. You might use custom SQL for a few specific reasons:

• Data Pre-aggregation: You can use functions like SUM() or COUNT() with a GROUP BY clause to aggregate data at the source. This can significantly improve dashboard performance by sending a smaller, pre-summarized dataset to Tableau.
• Complex Joins: While Tableau's joins are powerful, some scenarios involving multiple conditions or complex subqueries are just easier to write out in raw SQL.
• Union Data: If you need to stack data from several tables that have the same structure, a UNION ALL in SQL is the most direct way to do it.
• Accessing Database-Specific Features: Your database might have special functions (for handling dates, strings, or JSON) that aren't available in Tableau's standard calculation language. Custom SQL lets you leverage them directly.
• Filtering Data Early: Using a WHERE clause in your SQL statement filters data before it’s even brought into Tableau, which is more efficient than loading millions of records and then applying a data source filter.

A Step-by-Step Guide to Using and Checking Custom SQL

Let’s walk through the process from connecting to your data to getting a clean result from your query. For this example, we’ll imagine we're connecting to a SQL database with an 'Orders' table.

1. Connect to Your Data Source

First, open Tableau Desktop and connect to your database. In the Connect pane on the left, select your database type (e.g., Microsoft SQL Server, PostgreSQL, Amazon Redshift).

Enter your server credentials (server name, username, and password) and connect.

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

2. Open the Custom SQL Editor

Once you are connected, you’ll see the Data Source page. Instead of dragging tables from the left sidebar onto the canvas, find the option labeled New Custom SQL and drag it over.

This will open a dialog box with a new text editor. This is where you’ll write or paste your SQL query.

3. Write Your SQL Query

Now, let's write a simple query. Suppose we want to pull all order details, but only for orders shipped to Germany and only where the freight cost was greater than $50. The query would look something like this:

SELECT
  "OrderID",
  "OrderDate",
  "ShipCity",
  "ShipCountry",
  "Freight"
FROM "Orders"
WHERE "ShipCountry" = 'Germany' AND "Freight" > 50

Type or paste this query directly into the Custom SQL dialog box.

4. Check The Query with "Update Now"

This is the most critical step. After writing your query, your primary tool for checking it inside Tableau is the data preview grid at the bottom of the screen. To populate this grid, click the Update Now button (or Preview Results in the query dialog itself).

Here’s what happens when you click it:

1. Tableau sends your raw SQL query directly to your connected database.
2. The database executes the query.
3. If the query is valid and executes successfully, the database sends back a sample of the results (usually the first set of records).
4. Tableau displays this sample in the data grid.

Use the preview grid to sanity-check your results:

• Are the columns what you expect? Look at the column headers to make sure you selected the right fields and that your aliases (if you used any) are named correctly.
• Are the data types correct? Glance at the icons above each column header. Does Tableau recognize your date field as a date (#), your numerical fields as numbers (#), and text as strings (Abc)? If not, you may need to cast the data type in your SQL or change it manually in Tableau.
• Is the data filtered correctly? In our example, scan the 'ShipCountry' column to ensure every row shows "Germany" and check the 'Freight' column to see that all values are above 50. This confirms your 'WHERE' clause is working.

If the data looks good, you've successfully written and checked your query. If the grid is empty or you get an error message, then it's time to troubleshoot.

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

Troubleshooting Common Custom SQL Errors

Tableau isn’t a SQL development environment, so its error messages can be a bit generic. Usually, it's just passing on a message from the database. Here are some of the most common issues you'll run into and how to fix them.

Syntax Errors

This is the number one cause of problems. A simple typo, a misplaced comma, or a missing keyword will cause the query to fail.

• Example Error: You might see a pop-up saying, "Database error 0x80040E14: Syntax error..." followed by text from your database.

Common Causes:

• Typos: Forgetting a letter in a keyword, like writing 'SLECT' instead of 'SELECT'.
• Mismatched Quotes: Using a double quote where a single quote is required for a string value (e.g., WHERE City = "New York" should be WHERE City = 'New York' in standard SQL).
• Incorrect Table/Column Names: Getting the name of a table or field even slightly wrong. Remember that some databases are case-sensitive. "Orders" might be different from "orders".
• Missing Keywords: Forgetting a necessary keyword like FROM between your select list and your table name.

How to Fix It:

Carefully proofread your query. One helpful trick is to copy your query and paste it into a dedicated SQL editor (like DBeaver, SQL Server Management Studio, or an online SQL formatter). These tools often have better syntax highlighting and error-checking that can instantly flag your mistake.

Performance Issues (The Never-Ending Spinner)

Sometimes your query is syntactically correct, but when you click "Update Now," the loading spinner just keeps spinning forever. This usually means the query is highly inefficient and the database is struggling to execute it.

Common Causes:

• Using SELECT * on a wide table: Selecting all columns from a table with hundreds of columns puts unnecessary strain on the database and your network.
• Joining huge tables without filters: Joining two multi-million-row tables can create a massive result set that runs slowly or times out.
• Complex subqueries or calculations: Heavy calculations or layer upon layer of subqueries can bog down the database.

How to Fix It:

• Be specific: Only SELECT the exact columns you need for your visualization.
• Filter aggressively: Use WHERE clauses to reduce the amount of data as much as possible at the database level. For testing, add a LIMIT 100 clause to the end of your query to quickly see if it returns records without having to wait for the full dataset.
• Test in a SQL client: Run your query in a dedicated SQL tool. Most have a feature like 'EXPLAIN' or an "Execution Plan" viewer that shows you which parts of your query are the slowest so you can optimize them.

Data Type Mismatches

Your query might run successfully, but Tableau misinterprets a column's data type. For instance, a field with postal codes may be incorrectly classified as a number, causing Tableau to drop leading zeros (like in '01101').

How to Fix It:

1. Change the Data Type in Tableau: The easiest fix is often to click the data type icon (like the '#') above the column header in the Data Source page and change it to the correct type (e.g., 'String').
2. Use 'CAST' in SQL: For more permanent control, you can force the data type within the query itself using a 'CAST' function.

SELECT CAST("OrderID" AS VARCHAR) AS OrderID_String FROM "Orders"

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

Best Practices for Writing Custom SQL in Tableau

To avoid these issues from the start, follow a few best practices:

• Comment Your Code: Use SQL comments (-- This is a comment) to explain your logic. This helps you (and your teammates) understand the query when you revisit it months later.
• Use Parameters for Flexibility: Instead of hardcoding values (like 'Germany' in our example), use a Tableau Parameter. This allows you and dashboard users to dynamically change the value in a filter, and Tableau will re-run the query with the new value.

WHERE "ShipCountry" = <Parameters.CountryParameter>

• Develop in a Real SQL Editor: Write and test complex queries in a proper SQL client first. Once it's running perfectly there, then paste it into Tableau. The debugging tools are much better outside of Tableau.
• Ask if you really need it: Custom SQL is a powerful tool, but it's not always the right one. If you can achieve your goal using Tableau's native joins and relationships, that's often a better choice. The visual interface is easier to maintain, and Tableau's performance engine (Hyper) can sometimes optimize visual joins better than it can a fixed block of SQL code.

Final Thoughts

Checking a custom SQL query in Tableau is a process of writing your code, using the data preview grid to validate the output, and carefully troubleshooting any error messages the database sends back. By proofreading your syntax and testing the logic, you can combine the flexibility of SQL with Tableau’s powerful visualization capabilities.

For many teams, the process of writing, testing, and debugging SQL becomes a major time sink. Writing a simple query can be quick, but stitching together data from sources like Salesforce, Shopify, and Google Analytics often requires complex joins you would rather not manage. That's why we built Graphed. Instead of wrestling with syntax and data connections, you can just ask questions in plain English - like "Show me a chart of Shopify revenue vs Facebook ad spend by campaign for last month" - and get a live, interactive dashboard in seconds. We handle the complexity of translating your questions into efficient queries so you can get straight to the insights.