Was this page helpful?
Yes No
Have a comment? Please leave it here. Thanks for your feedback!
All Tableau Help > Tableau Desktop and Web Authoring Help > 
Applies to: Tableau Desktop

Run Initial SQL

When connecting to some databases, you can specify an initial SQL command that will run when a connection is made to the database, for example, when you open the workbook, refresh an extract, sign in to Tableau Server, or publish to Tableau Server. Initial SQL is not run when your refresh your view. Note that this initial SQL is different than a custom SQL connection. A custom SQL connection defines a relation (or table) to issue queries against. For more information, see Connect to a Custom SQL Query.

You can use this command to:

You have the option to add an initial SQL command in the Server Connection dialog box or on the Data Source page.

Note: If your data source supports running an initial SQL statement, an Initial SQL link appears in the lower-left corner of the Server Connection dialog box. For information about your data source, see Supported Connectors.

To use initial SQL

  1. In the Server Connection dialog box, click Initial SQL. Or, on the Data Source page, select Data > Initial SQL or Data > Query Banding and Initial SQL depending on the database you connect to.

  2. Enter the SQL command into the Initial SQL dialog box. You can use the Insert drop-down menu to pass parameters to your data source.

Note: Tableau does not examine the statement for errors. This SQL statement is simply sent to the database when you connect.

Your software license may restrict you from using initial SQL with your connection. If you publish to Tableau Server, the server must be configured to allow Initial SQL statements. By default, the server software is configured to allow these statements to run when the workbook is loaded in a web browser. Administrators can disable the functionality on the Data Connections tab of the Tableau Server Configuration utility. If the server does not allow initial SQL statements, the workbook opens, but the initial SQL commands are not sent.

Parameters in an initial SQL statement

You can pass parameters to your data source in an initial SQL statement. There are several reasons why this is useful:

The following parameters are supported in an initial SQL statement:

Parameter Description Example of returned value
TableauServerUser The user name of the current server user. Use when setting up impersonation on the server. Returns an empty string if the user is not signed in to Tableau Server. asmith
TableauServerUserFull The user name and domain of the current server user. Use when setting up impersonation on the server. Returns an empty string if the user is not signed in to Tableau Server. domain.lan\asmith
TableauApp The name of the Tableau application.

Tableau Desktop Professional

Tableau Server

TableauVersion The version of the Tableau application. 9.3
WorkbookName The name of the Tableau workbook. Use only in workbooks with an embedded data source. Financial-Analysis


The following examples show different ways you can use parameters in an initial SQL statement.

Defer execution to the server

You can defer an initial SQL statement so that it is executed only on the server. One reason to defer execution to the server is if you don’t have permission to execute the commands that set up impersonation. Use <ServerOnly></ServerOnly> tags to enclose the commands to be executed only on the server.


CREATE TEMP TABLE TempTable(x varchar(25));
<ServerOnly>INSERT INTO TempTable Values(2);</ServerOnly>

Security and impersonation

If you use the TableauServerUser or TableauServerUserFull parameter in an initial SQL statement, you will create a dedicated connection that can’t be shared with other users. This will also restrict cache sharing, which can enhance security, but may also slow performance.