What is Initial SQL in Tableau?

Tableau's Initial SQL feature lets you run a custom SQL command the moment you connect to a database, acting as a powerful setup script for your data source. Think of it as giving instructions to your database on how to prepare the data environment before any visualizations are even built. In this tutorial, we’ll walk through what Initial SQL is, how it differs from Custom SQL, and several practical examples of how to use it to improve performance and security.

Graphed

Still Building Reports Manually?

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

Watch the Demo

What Exactly is Initial SQL in Tableau?

Initial SQL is a feature available for many database connections in Tableau that executes a specified SQL block once, at the very beginning of a session. A session is created whenever you:

• Open a workbook that connects to the data source.
• Edit the connection.
• Refresh an extract.
• Connect to the data source in Tableau Server/Cloud.

The key here is that it runs once. Its primary job is not to pull the final dataset you'll be visualizing, but rather to prepare the database environment for the queries Tableau will send later. This setup work can include creating temporary tables, setting user-specific variables for security, or configuring session parameters to optimize performance.

This is completely different from a Custom SQL query, which defines the entire data set Tableau works with and is re-run every time a worksheet is updated.

Common Use Cases for Initial SQL

At its core, Initial SQL is about running setup tasks on the database server before Tableau requests any data. This gives you a lot of control to streamline, secure, and shape your data before it ever hits your workbook. Let's look at the most common scenarios.

Graphed

Still Building Reports Manually?

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

Watch the Demo

1. Create temporary tables for complex data shaping

This is arguably the most powerful use of Initial SQL. Imagine you have a complex database schema where the data you need is spread across multiple tables and requires significant joining and aggregation to be useful. Performing these heavy operations inside Tableau with joins or data blending can slow down your dashboard, especially with large datasets.

Instead, you can use Initial SQL to perform the heavy lifting on the database side and load the results into a temporary table. Tableau can then query this simple, pre-aggregated temporary table, resulting in much faster performance.

Example: Summarizing daily sales data

Let's say you want to create a clean, aggregated view of daily sales orders. Your database has a sales table, a products table, and a customers table. You can use Initial SQL to join these, calculate the final price, and put it all in one temporary table.

-- Create a temporary table that will only exist for this session
CREATE TEMPORARY TABLE DailySalesSummary AS

SELECT
  o.order_date,
  c.customer_segment,
  p.product_category,
  SUM(o.quantity * p.price) as total_sales
FROM orders o
LEFT JOIN customers c ON o.customer_id = c.customer_id
LEFT JOIN products p ON o.product_id = p.product_id
GROUP BY 1, 2, 3,

After running this Initial SQL command, you can then simply drag the DailySalesSummary table onto the Tableau canvas or use a simple Custom SQL query like SELECT * FROM DailySalesSummary. All subsequent queries from your dashboard will be hitting this clean, super-fast temp table instead of running complex joins repeatedly.

Graphed

Still Building Reports Manually?

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

Watch the Demo

2. Implement dynamic row-level security

Initial SQL is perfect for implementing row-level security by using Tableau's built-in parameters, especially the [TableauServerUser] parameter.

The idea is to capture the logged-in user's username when they open the dashboard and use it to filter the data. You can set a session-level variable in the database that holds the current user's name, which can then be used by your database views or Custom SQL queries to restrict data visibility.

Example: Setting a user context variable

In a PostgreSQL database, you could use the following command to create a session variable called current_user.id that stores the Tableau username.

-- Set a runtime parameter for the current Tableau username
SET MY.USER_ID = '[TableauServerUser]',

(Note: The exact syntax for setting session variables changes depending on your database. For SQL Server, it might be EXEC sp_set_session_context 'user_name', '[TableauServerUser]'.)

Now, your database administrator can create a secure view that uses this variable to filter data. The view might look something like this:

CREATE VIEW SecureSalesData AS
SELECT *
FROM AllSalesData
WHERE SalesRepUsername = current_setting('MY.USER_ID', TRUE),

When you connect to this SecureSalesData view in Tableau, the data is automatically filtered for the user viewing the dashboard, without you needing to apply any user filters within Tableau itself.

3. Use Tableau parameters to pre-filter data

Just like you can pass the Tableau username, you can also pass any other Tableau parameter into your Initial SQL script. This is incredibly useful for dynamic, coarse-level filtering that dramatically reduces the amount of data transferred to Tableau.

Example: Filtering data by a specific region

Imagine you have a dashboard that analyzes performance for a single business region at a time, chosen from a dropdown filter. Instead of pulling the entire global dataset into Tableau and then filtering, you can use a parameter to tell the database to only provide data for that one region.

First, you would create a Tableau Parameter named RegionParameter. Then, in your Initial SQL, you would do something like this:

-- Create a temporary table that only contains data for the selected region
CREATE TEMPORARY TABLE FilteredRegionalSales AS
SELECT *
FROM AllSalesData
WHERE region = '[Parameters].[RegionParameter]',

When a user selects "North America" from the parameter dropdown, Tableau will send region = 'North America' to the database. The temporary table FilteredRegionalSales will be built with only North American sales data. Your entire dashboard will now run interactions and filter actions against this much smaller dataset, making it incredibly responsive.

Graphed

Still Building Reports Manually?

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

Watch the Demo

How to Configure Initial SQL in Tableau Desktop

Setting this up is straightforward. Here’s a quick step-by-step guide:

1. Connect to Data: Open Tableau and connect to a supported database, such as PostgreSQL, MySQL, SQL Server, or Amazon Redshift.
2. Find the Initial SQL Option: On the Data Source page, look in the bottom left corner of the connection pane. You will see an option labeled Initial SQL.
3. Open the Command Dialog: Double-click on Initial SQL to open the "Initial SQL Command" dialog box.
4. Enter Your Script: Write or paste your SQL script into the text field. If you want to use a Tableau parameter, you can use the Insert Parameter dropdown menu on the right.
5. Click OK: Once you click OK, Tableau will immediately run this command against your database to establish the connection's environment.
6. Define Your Data: At this point, you still need to tell Tableau what data to use. You can either drag a table or view to the canvas, or open a Custom SQL editor to query the temporary table you just created.

Initial SQL vs. Custom SQL: What's the Difference?

This is an important distinction. While they both involve writing SQL, they serve completely different purposes.

• Initial SQL
• Custom SQL

In short: use Initial SQL to stage your environment and Custom SQL to retrieve staged data.

Final Thoughts

Initial SQL is a fantastic feature for any Tableau developer who needs more control over how their data is prepared and delivered. By running server-side setup scripts to create temporary tables, set session variables for security, or pre-filter datasets with parameters, you can significantly improve the performance, security, and scalability of your dashboards.

Mastering tools like Initial SQL in Tableau is a great way to optimize reports, but that process still requires a deep understanding of SQL and database logic. We built Graphed to remove this complexity altogether. Instead of writing prep scripts, you simply connect your data sources in seconds and ask questions conversationally, like "create a dashboard comparing ad spend vs revenue for my top 5 campaigns last month," and get a live, interactive dashboard built for you instantly.