Tableau's Custom SQL connection lets you write a SQL query as the data source rather than connecting to a table directly. It is useful for specific scenarios and counterproductive in others. This guide covers the cases where Custom SQL is the right answer and the performance implications.
Tableau's Custom SQL connection allows you to write a SQL query as the foundation of a data source, rather than connecting to a table or view directly. Tableau sends your Custom SQL as a subquery when generating view queries — wrapping its own SQL around yours. This is useful in specific scenarios and harmful in others. Understanding when Custom SQL helps versus hurts is essential for maintaining performant, maintainable Tableau workbooks.
What Custom SQL does
When you connect to a table in Tableau, Tableau generates SQL against the table directly: SELECT ... FROM table WHERE ... GROUP BY .... When you use Custom SQL, Tableau wraps your query: SELECT ... FROM (your custom SQL) WHERE ... GROUP BY ....
The resulting SQL is a nested query. The database receives Tableau's query, which internally queries your Custom SQL query, which queries the underlying tables. Most modern databases handle this efficiently — the query planner can push predicates into the subquery and optimise the combined execution. Some databases handle it less well, resulting in materialization of the inner query before outer predicates are applied.
When Custom SQL is appropriate
**Parameterised queries with Tableau parameters**: Custom SQL is the primary way to inject Tableau parameter values into the SQL sent to the database. If you need a where clause that uses a Tableau parameter value — filtering by a date parameter, a region parameter, or an account ID parameter — Custom SQL enables this. Example: WHERE order_date >= DATETRUNC('month', [Parameter: Month Start]). This is not achievable through the standard table connection.
**Complex joins not achievable through the data model**: Tableau's data model (Relationships, introduced in Tableau 2020.2) handles most multi-table scenarios well. But some complex joins — non-equi joins, multiple join conditions with OR logic, self-joins with aliasing — cannot be expressed through the data model. Custom SQL handles these directly.
**Database-specific SQL features**: Certain database functions or query constructs are not surfaced through Tableau's standard connection interface. A window function over a specific partition that affects the row set before Tableau aggregates, a lateral join for unnesting arrays, a database-specific syntax for sampling — Custom SQL enables these.
**Stored procedure calls**: Some databases support connecting to stored procedures as data sources. Tableau's Custom SQL can call a stored procedure for some data sources, passing parameters to the procedure.
When Custom SQL hurts performance
**Replacing simple table connections**: Using Custom SQL to run SELECT * FROM table is worse than connecting to the table directly. Tableau adds its own filters and aggregations to table connections and can optimise the full query. SELECT * in a Custom SQL subquery forces the database to materialise all columns and rows in the subquery before Tableau's WHERE clause is applied. Connect to the table directly and let Tableau generate the optimal query.
**Materializing large subqueries**: Custom SQL queries that return millions of rows are processed as subqueries. If Tableau's outer WHERE clause filter could have been applied at the source table level, applying it to the Custom SQL subquery may be less efficient — depending on whether the database's query planner pushes the predicate into the subquery.
**Blocking extract generation**: Tableau extracts are built by executing the data source query. A Custom SQL that returns 500 million rows before Tableau's filters are applied will create a massive, slow extract. Standard table connections allow Tableau to add extract filters that reduce data at query time.
**Undermining data blending efficiency**: Custom SQL data sources used in data blending are always queried at the dimension level returned by the Custom SQL — Tableau cannot push down filter context into the Custom SQL subquery for the secondary connection. This is a significant limitation for complex blending scenarios.
Alternatives to Custom SQL
Before reaching for Custom SQL, consider:
**Database views or stored procedures**: Create a view in the database that encapsulates the complex join or transformation logic. Connect Tableau to the view. The view is maintainable, documentable, and accessible to other tools without embedding SQL in the Tableau workbook. This is the most maintainable approach for complex transformations.
**Tableau Prep**: Complex data preparation — multi-step cleaning, aggregation, restructuring — is better handled in Tableau Prep (or a dbt model) than in Custom SQL. The output is a clean published data source that Tableau connects to as a table.
**Tableau's data model (Relationships)**: For most multi-table join scenarios, Tableau's relationship model is the correct tool. Relationships are more flexible than Custom SQL joins and allow Tableau to optimise query generation per measure.
**Calculated fields**: Business logic that filters or transforms data — applying conditionals, parsing strings, computing metrics — belongs in Tableau calculated fields, not in Custom SQL. Calculated fields are visible in the data pane, testable, and don't affect the query generation for unrelated measures.
Maintenance implications
Custom SQL embeds SQL queries directly in the Tableau workbook or data source. When the database schema changes (a column renamed, a table restructured), the Custom SQL must be manually updated in every workbook that uses it. A database view or dbt model is updated once; all Tableau workbooks connecting to it receive the update automatically.
For production workbooks used by many users, minimise Custom SQL. Where it is necessary, publish the Custom SQL as a Published Data Source rather than embedding it in individual workbooks — updates to the data source propagate to all consuming workbooks.
For the data source connection context, see tableau data sources guide and tableau extract guide. Our Tableau consulting practice reviews and refactors Custom SQL data sources as part of workbook performance audits — book a free audit if your workbooks are slow or difficult to maintain.
A former Microsoft data architect audits your data foundation, identifies your top priorities, and sends you a written plan. Free. No pitch.
Book a Call →