feat: async query submission, status, results, and cancellation

[krinart]

Adds asynchronous query support: queryAsync(sql) / queryAsyncWithParams(sql, params...) submit a query and return an AsyncQuery handle (status(), waitForCompletion(), results(), cancel()), backed by the Spice runtime's Flight DoAction async-query actions. This requires the runtime to be running in distributed/scheduler mode.

This brings spice-java up to parity with the equivalent (currently unreleased) capability in gospice. Unlike gospice's v9, which made this change by repurposing Query/QueryWithParams (a breaking change), this SDK keeps query()/queryWithParams() untouched and adds the async path as new, additive API under an Async-suffixed name, consistent with spice-dotnet's naming convention and this SDK's japicmp compatibility gate.

Includes unit tests against an in-process mock Flight server (no live runtime required) and a README section.

[Copilot]

Pull request overview

Adds additive asynchronous query execution through Flight DoAction, including status polling, cancellation, and Arrow result retrieval.

Changes:

• Adds async query APIs and lifecycle status handling.
• Implements chunked Arrow result reading.
• Adds mock-server tests and usage documentation.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
SpiceClient.java	Implements async Flight actions and public submission APIs.
AsyncQuery.java	Provides polling, cancellation, and result access.
AsyncQueryResultReader.java	Streams chunked Arrow results.
QueryStatus.java	Defines async query lifecycle states.
AsyncQueryTest.java	Tests async query behavior.
TestFlightSqlServer.java	Mocks async Flight actions.
README.md	Documents async query usage.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Suppressed comments (3)

src/main/java/ai/spice/AsyncQueryResultReader.java:122

• results() passes Math.max(chunkCount, 1), so this reader cannot distinguish a declared zero-chunk result from a real one-chunk result. Any ExecutionException while fetching the sole real chunk (for example expiration, authentication, or transport failure) is therefore silently converted into a successful empty reader. Preserve the declared count separately and suppress the missing chunk only when total_chunk_count was actually zero.

            if (index == 0 && chunkCount <= 1) {
                return false;

src/main/java/ai/spice/AsyncQuery.java:108

• The timeout does not bound this wait. A status RPC can block past the deadline, and the unconditional 500 ms sleep can overshoot a shorter timeout; the next poll may even return SUCCEEDED after the deadline and be accepted because terminal status is checked first. Propagate the remaining deadline to each status DoAction and cap polling sleep to the remaining duration.

    public QueryStatus waitForCompletion(Duration timeout) throws ExecutionException {
        long deadlineNanos = (timeout == null) ? -1 : System.nanoTime() + timeout.toNanos();
        while (true) {
            QueryStatus current = status();

src/main/java/ai/spice/SpiceClient.java:1827

• This applies withQueryTimeout to GetAsyncQueryResult, so downloading a large async result chunk can be aborted by the planning timeout. That contradicts the documented contract in SpiceClientBuilder.java:244-247 that result streaming is not limited by this timeout. Use the auth-only stream options for the result action while retaining callOptions for control-plane actions.

            Iterator<Result> results = channel.rawClient.doAction(new Action(actionType, requestBody),
                    channel.callOptions);

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

src/main/java/ai/spice/AsyncQuery.java:118

• A finite timeout is inferred from the sign of deadlineNanos, but System.nanoTime() has an arbitrary origin and may be negative, and adding the duration can overflow. In either case deadlineNanos >= 0 can be false and this method silently treats a finite timeout as an indefinite wait. Track timeout != null separately and compute remaining time from elapsed nanoTime() differences rather than using the deadline's sign as a sentinel.

        long deadlineNanos = (timeout == null) ? -1 : System.nanoTime() + timeout.toNanos();
        while (true) {
            Duration remaining = null;
            if (deadlineNanos >= 0) {

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

src/main/java/ai/spice/AsyncQuery.java:115

• System.nanoTime() may be negative, and adding a finite timeout may wrap into the sign bit. Using deadlineNanos >= 0 as the bounded/unbounded sentinel can therefore turn a bounded wait into an indefinite one. Track whether a timeout was supplied separately; nano-time subtraction remains valid across wraparound.

        long deadlineNanos = (timeout == null) ? -1 : System.nanoTime() + timeout.toNanos();

src/main/java/ai/spice/AsyncQuery.java:170

• These are two different status snapshots. The runtime defines CLOSED as expired results, so if a query changes from SUCCEEDED during waitForCompletion() to CLOSED on this poll, finalStatus still passes the success check while this response has no result metadata. The reader then defaults to zero chunks and suppresses the missing chunk-0 error, silently returning an empty result. Use the status from the same response as the metadata (or return the terminal response from the wait helper).

        QueryStatus finalStatus = waitForCompletion();
        JsonObject statusResponse = this.client.asyncQueryStatus(this.queryId);