feat(query): parameterized async /v1/queries submit + options

[lukekim]

Summary

Completes the async /v1/queries API for Spice v2. The API (added in #68/#70) already covered submit / list / status / results / cancel, but submit hardcoded parameters/timeout_seconds/maximum_size to None, so parameterized async distributed queries weren't exposed — even though the sync Flight path already has sql_with_bindings.

Verified against the handler at spiceai/spiceai@v2.1.0 (crates/runtime/src/http/v1/queries.rs).

New API

// Positional $1, $2, ... bindings (mirrors the sync sql_with_bindings):
let job = client.query_with_bindings(
    "SELECT * FROM large_table WHERE status = $1",
    QueryParameters::new().push("active"),
).await?;

// Bindings + submit controls:
let job = client.query_with_options(
    sql,
    QuerySubmitOptions::new()
        .bindings(QueryParameters::new().push("active"))
        .timeout_seconds(300)
        .maximum_size(100_000_000),
).await?;

• QuerySubmitOptions builder (bindings/timeout_seconds/maximum_size), exported from the crate root.
• QueryParameters::to_json_values() encodes scalar bindings as the JSON array the HTTP API expects; binary/array/non-finite params fail fast with QueryError::InvalidParameter before any request.
• query(sql) unchanged as the no-args shortcut.

Tests

• cargo test --lib — 187 passed (+9: 6 param-encoding unit tests incl. reject-binary/array/NaN, 3 wiremock tests asserting the exact request body).
• cargo test --doc — README + rustdoc examples compile.

Note on #79

This branch is cut from the current (unformatted) trunk. #79 (cargo fmt --all + rustfmt CI gate) reformats pre-existing lines in params.rs/client.rs, so whichever of the two merges second will need a trivial rebase — I can handle that. My added code is already rustfmt-clean, so it will pass the new fmt gate once rebased.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR completes the async /v1/queries submit API in the Spice.ai Rust SDK by exposing parameter bindings and submit-time controls (timeout and max result size), bringing parity with the sync Flight sql_with_bindings path.

Changes:

• Add QuerySubmitOptions (bindings/timeout_seconds/maximum_size) and surface query_with_bindings + query_with_options on the async HTTP query client API.
• Implement QueryParameters::to_json_values() to encode scalar bindings as the JSON array expected by /v1/queries, with fast-fail errors for unsupported parameter kinds.
• Re-export QuerySubmitOptions from the crate root and document the new async query usage (README + rustdoc).

Reviewed changes

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

Show a summary per file

File	Description
src/query.rs	Adds QuerySubmitOptions and extends HTTP submit to accept parameters + submit controls.
src/params.rs	Adds JSON encoding for scalar parameters used by async /v1/queries bindings.
src/lib.rs	Re-exports QuerySubmitOptions from the crate root.
src/client.rs	Adds query_with_bindings / query_with_options and updates submit wiring + tests.
README.md	Documents async query bindings and submit options usage.

Comments suppressed due to low confidence (1)

src/client.rs:335

• This note links to SpiceClientBuilder::http_url, but the builder is exported publicly as ClientBuilder. Referring to the public API name avoids broken/confusing rustdoc links for external users.

    /// **Note:** Requires [`http_url()`](SpiceClientBuilder::http_url) to be configured.