SQL Server query hints

[joserocha]

Bug description

I am trying to create a chart that queries a SQL Server instance. To prevent excessive resource consumption, I am using the query hint OPTION (MAXDOP 1). It works perfectly in SqlLab, but when creating the chart, it triggers the following error:

Data error
Error: (156, b"Incorrect syntax near the keyword 'OPTION'.DB-Lib error message 20018, severity 15:\nGeneral SQL Server error: Check messages from the SQL Server\n")

Is there anything I can do to overcome this error?

Screenshots/recordings

2026-03-14 02:09:33,479:WARNING:superset.connectors.sqla.models:Query SELECT TOP 50
<my_query> OPTION(
MAXDOP 1
)) AS virtual_table ORDER BY [column] DESC on schema None failed
Traceback (most recent call last):
File "/app/superset/connectors/sqla/models.py", line 1659, in query
df = self.database.get_df(
File "/app/superset/models/core.py", line 710, in get_df
self.db_engine_spec.execute(cursor, sql_, self)
File "/app/superset/db_engine_specs/base.py", line 1855, in execute
raise cls.get_dbapi_mapped_exception(ex) from ex
File "/app/superset/db_engine_specs/base.py", line 1851, in execute
cursor.execute(query)
File "src/pymssql/_pymssql.pyx", line 465, in pymssql._pymssql.Cursor.execute
pymssql.exceptions.OperationalError: (156, b"Incorrect syntax near the keyword 'OPTION'.DB-Lib error message 20018, severity 15:\nGeneral SQL Server error: Check messages from the SQL Server\n")

Superset version

master / latest-dev

Python version

3.9

Node version

16

Browser

Chrome

Additional context

No response

Checklist

• I have searched Superset docs and Slack and didn't find a solution to my problem.
• I have searched the GitHub issue tracker and didn't find a similar bug report.
• I have checked Superset's logs for errors and if I found a relevant Python stacktrace, I included it here as text in the "additional context" section.

[dosubot[bot]]

This is a known limitation with how Superset processes SQL queries differently between SQL Lab and charts.

Why it happens: When creating charts, Superset wraps queries in subqueries to apply limits and other transformations. SQL Server's OPTION clauses must appear at the end of the outermost query, so when your query gets wrapped, the OPTION (MAXDOP 1) ends up inside a subquery where it's syntactically invalid.

This is part of a broader pattern affecting T-SQL features since Superset adopted sqlglot for SQL parsing in 4.1.0+.

Workarounds:

1. Create a database view - Encapsulate your query with the OPTION hint in a SQL Server view, then query that view from Superset charts
2. Set MAXDOP at the database level - Configure query governor settings in SQL Server itself rather than per-query hints
3. Use SQL Lab for reporting - If you don't need the chart visualization, SQL Lab can execute the query directly

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[fowlerp397-tech]

Any updates on this

…

On Sat, Mar 14, 2026, 8:55 AM dosubot[bot] ***@***.***> wrote: *dosubot[bot]* left a comment (apache/superset#38650) <#38650 (comment)> This is a known limitation with how Superset processes SQL queries differently between SQL Lab and charts. *Why it happens:* When creating charts, Superset wraps queries in subqueries to apply limits and other transformations. SQL Server's OPTION clauses must appear at the end of the *outermost* query, so when your query gets wrapped, the OPTION (MAXDOP 1) ends up inside a subquery where it's syntactically invalid. This is part of a broader pattern affecting T-SQL features <#31913> since Superset adopted sqlglot for SQL parsing in 4.1.0+. *Workarounds:* 1. *Create a database view* - Encapsulate your query with the OPTION hint in a SQL Server view, then query that view from Superset charts 2. *Set MAXDOP at the database level* - Configure query governor settings in SQL Server itself rather than per-query hints 3. *Use SQL Lab for reporting* - If you don't need the chart visualization, SQL Lab can execute the query directly *To reply, just mention @dosu <https://go.dosu.dev/dosubot?utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=brand-link>.* ------------------------------ How did I do? Good <https://app.dosu.dev/response-feedback/450659a3-0abf-4a4c-b25c-69c4a9fcd940?feedback_type=great_response&utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-great_response> | Irrelevant <https://app.dosu.dev/response-feedback/450659a3-0abf-4a4c-b25c-69c4a9fcd940?feedback_type=irrelevant_answer&utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-irrelevant_answer> | Incorrect <https://app.dosu.dev/response-feedback/450659a3-0abf-4a4c-b25c-69c4a9fcd940?feedback_type=incorrect_sources&utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-incorrect_sources> | Verbose <https://app.dosu.dev/response-feedback/450659a3-0abf-4a4c-b25c-69c4a9fcd940?feedback_type=too_verbose&utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-too_verbose> | Hallucination <https://app.dosu.dev/response-feedback/450659a3-0abf-4a4c-b25c-69c4a9fcd940?feedback_type=hallucination&utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-hallucination> | Report 🐛 <https://app.dosu.dev/response-feedback/450659a3-0abf-4a4c-b25c-69c4a9fcd940?feedback_type=bug_report&utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-bug_report> | Other <https://app.dosu.dev/response-feedback/450659a3-0abf-4a4c-b25c-69c4a9fcd940?feedback_type=other&utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=feedback-other> [image: Chat with Dosu] <https://app.dosu.dev/a28d3c7e-a9d3-459e-9fb6-3a6f9ff4f357/ask?utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=chat-badge> [image: Open in Cursor] <https://cursor.com/link/prompt?text=This%20is%20a%20known%20limitation%20with%20how%20Superset%20processes%20SQL%20queries%20differently%20between%20SQL%20Lab%20and%20charts.%0A%0A%2A%2AWhy%20it%20happens%3A%2A%2A%20When%20creating%20charts%2C%20Superset%20wraps%20queries%20in%20subqueries%20to%20apply%20limits%20and%20other%20transformations.%20SQL%20Server%27s%20%60OPTION%60%20clauses%20must%20appear%20at%20the%20end%20of%20the%20%2Aoutermost%2A%20query%2C%20so%20when%20your%20query%20gets%20wrapped%2C%20the%20%60OPTION%20%28MAXDOP%201%29%60%20ends%20up%20inside%20a%20subquery%20where%20it%27s%20syntactically%20invalid.%0A%0AThis%20is%20part%20of%20a%20%5Bbroader%20pattern%20affecting%20T-SQL%20features%5D%28https%3A//github.com/apache/superset/issues/31913%29%20since%20Superset%20adopted%20sqlglot%20for%20SQL%20parsing%20in%204.1.0%2B.%0A%0A%2A%2AWorkarounds%3A%2A%2A%0A1.%20%2A%2ACreate%20a%20database%20view%2A%2A%20-%20Encapsulate%20your%20query%20with%20the%20OPTION%20hint%20in%20a%20SQL%20Server%20view%2C%20then%20query%20that%20view%20from%20Superset%20charts%0A2.%20%2A%2ASet%20MAXDOP%20at%20the%20database%20level%2A%2A%20-%20Configure%20query%20governor%20settings%20in%20SQL%20Server%20itself%20rather%20than%20per-query%20hints%0A3.%20%2A%2AUse%20SQL%20Lab%20for%20reporting%2A%2A%20-%20If%20you%20don%27t%20need%20the%20chart%20visualization%2C%20SQL%20Lab%20can%20execute%20the%20query%20directly> [image: Join Discord] <https://go.dosu.dev/discord-bot?utm_source=github&utm_medium=bot-comment&utm_campaign=github-assistant&utm_content=join-discord> [image: Share on X] <https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/apache/superset/issues/38650> — Reply to this email directly, view it on GitHub <#38650 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/B72HASIDHZ6AQEU4NI7W37D4QVQE5AVCNFSM6AAAAACWR4XUDSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DANRQGU4TAMBZHA> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[sadpandajoe]

Going to move this over to a discussion.

[manimovassagh]

The Dosu explanation is correct about the root cause -- Superset wraps your virtual dataset query in a subquery, and OPTION (MAXDOP 1) can only appear at the outermost level of a SQL Server statement. It gets buried inside the subquery and SQL Server rejects it.

The database view workaround is the most practical path, but there's a subtlety: you cannot put OPTION hints inside a view definition either. SQL Server doesn't allow query hints in views.

What you can do:

1. Use a stored procedure + virtual dataset -- Create a stored proc with the hint, then query it from SQL Lab:

   CREATE PROCEDURE dbo.sp_my_report AS
   BEGIN
       SELECT col1, col2, col3
       FROM my_table
       WHERE ...
       OPTION (MAXDOP 1)
   END

   Then in SQL Lab: EXEC dbo.sp_my_report and save as virtual dataset. The catch is that Superset won't try to wrap EXEC statements in subqueries.

2. Set MAXDOP at the connection level -- In your Superset database connection settings, add an engine_params override:

   {
     "connect_args": {
       "appname": "superset"
     }
   }

   Then configure a Resource Governor workload group in SQL Server that caps MAXDOP for connections from Superset:

   CREATE WORKLOAD GROUP SupersetGroup WITH (MAX_DOP = 1);
   CREATE FUNCTION dbo.fn_classify_superset()
   RETURNS sysname WITH SCHEMABINDING AS
   BEGIN
       IF APP_NAME() = 'superset' RETURN 'SupersetGroup';
       RETURN 'default';
   END;
   ALTER RESOURCE GOVERNOR WITH (CLASSIFIER_FUNCTION = dbo.fn_classify_superset);
   ALTER RESOURCE GOVERNOR RECONFIGURE;

   This applies the MAXDOP limit to all queries from Superset without touching individual queries.

3. Database-scoped configuration -- If you can set it for the entire database:

   ALTER DATABASE SCOPED CONFIGURATION SET MAXDOP = 1;

   This is the simplest option if the database is dedicated to analytics workloads.

Option 2 gives you the most control without affecting other applications.

[gayathridevi1993]

This issue is likely related to how Apache Superset wraps the query internally when generating charts.

In SQL Server, the OPTION (MAXDOP 1) query hint must appear at the end of the final SELECT statement. However, Superset wraps the query inside a subquery (virtual table), as seen in the log:

SELECT TOP 50
<your_query> OPTION (MAXDOP 1)
) AS virtual_table

Because of this wrapping, the OPTION clause is no longer at the valid position, which results in the syntax error:
"Incorrect syntax near the keyword 'OPTION'"

Possible Workarounds

1. Remove OPTION (MAXDOP 1) from the query when using Superset charts

   • This is the simplest approach if parallelism is not critical

2. Use a database-level or server-level configuration for MAXDOP

   • This avoids the need for query-level hints

3. Create a view or stored procedure in SQL Server

   • Apply the query hint inside the view/SP
   • Then query the view from Superset without the OPTION clause

4. Check if Superset allows disabling query wrapping for your dataset

   • In some cases, using a saved dataset instead of a custom SQL query may help

Summary

The issue is not with SQL Server itself but with how Superset rewrites the query. Since SQL Server does not allow OPTION hints inside subqueries, this leads to the syntax error.

Let me know if this helps or if you need help testing one of the workarounds.