[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 every async query and error parsing for plain-text responses; older engines may reject async calls that previously worked with JSON output format.

Overview
Server-side execute_async now requests output_format=NULL instead of JSON, so newer Firebolt engines (4.32.13+) can accept async SELECT statements that require no result serialization. Statement planners pass async_execution into _get_output_format for fb_numeric, qmark, and bulk-insert paths; streaming plus async is explicitly rejected with an assert.

Error handling in raise_error_from_response tries to parse JSON structured errors even when the response is labeled text/plain, which matches NULL-format async failures.

Docs note that async SELECT is allowed on supported engines but results still cannot be fetched (fetch after async still errors). Tests add test_select_async (sync and asyncio), update unit expectations and HTTP mocks for NULL format, and add coverage for structured errors on plain-text responses.

Deploy note: all async integration tests (including existing INSERT async tests) need an engine that supports NULL output format.

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

[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.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 11f9832. 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