[pscls]

Summary

Newer Firebolt versions accept server-side async SELECT queries if the request asks for no result serialization. This PR makes the SDK send output_format=NULL for every execute_async call. Before, it sent JSON_Compact.

• _get_output_format returns the new NULL_OUTPUT_FORMAT constant for async execution. This covers the fb_numeric, qmark and qmark bulk-insert planners.
• Requesting streaming and async execution together now fails an assert.
• Docs: async SELECT queries are accepted, but their results can't be retrieved yet.
• New integration test test_select_async, added to both the sync and asyncio test suites.

⚠️ Before merging

Integration tests don't run on PRs. If staging's default engine is older than the version that accepts output_format=NULL, the async integration tests will fail, including the existing INSERT ones. Run the Integration tests FB 2.0 workflow by hand with engine-version set to a version that supports this, and only merge once that version is on staging.

Testing

• Unit tests: 794 passed, 1 skipped
• black, isort and mypy pass
• Integration tests not run yet (see above)

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes the HTTP contract for all execute_async calls; requires a Firebolt engine version that accepts output_format=NULL, or existing async integration tests will fail.

Overview
Server-side execute_async requests now send output_format=NULL instead of JSON_Compact, so newer Firebolt engines can accept async SELECT when no result serialization is requested.

BaseStatementPlanner._get_output_format takes an async_execution flag and returns the new NULL_OUTPUT_FORMAT constant for async paths (fb_numeric, qmark, and bulk insert). Combining streaming and async now fails an assertion.

Docs clarify that async SELECT may be submitted but results cannot be fetched yet; fetch* after execute_async still raises MethodNotAllowedInAsyncError. Sync/async integration tests add test_select_async; unit tests and HTTP mocks expect NULL on async query URLs.

^{Reviewed by Cursor Bugbot for commit eedb55f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[TimoDoering-firebolt]

🤖 Major: This makes every execute_async depend on the engine accepting NULL, not just async SELECT. Engines from before the async SELECT change reject the Null output format without advanced_mode ("Output format 'NULL' is not supported, choose one of: ..."). So after the SDK upgrade, async INSERT / COPY / VACUUM break against any older engine. The "Before merging" note covers staging, but not customers. Firebolt Core users pin image tags. The SDK release is not tied to the engine rollout. I see three options. We keep JSON_Compact as the default and send NULL only for SELECT (when the statement is parsed). Or we fall back to JSON_Compact on that specific format error. Or we hold the release until every supported engine and Core image has the engine change, and document the minimum version. I'd prefer one of the first two, so the SDK stays compatible with older engines.

[TimoDoering-firebolt]

🤖 Minor: This should say from which Firebolt version async SELECT is accepted. Older engines still reject it. With this PR as is, they would reject all async queries from this SDK version (see the comment on statement_planners.py). Also, the " - " reads like a broken dash. Two sentences would be cleaner.