Skip to content

feat: add nsql and nsql_generate_sql for the runtime's /v1/nsql endpoint - #92

Merged
sgrebnov merged 1 commit into
spiceai:trunkfrom
claudespice:feat/nsql
Aug 19, 2026
Merged

feat: add nsql and nsql_generate_sql for the runtime's /v1/nsql endpoint#92
sgrebnov merged 1 commit into
spiceai:trunkfrom
claudespice:feat/nsql

Conversation

@claudespice

Copy link
Copy Markdown
Contributor

What

Adds Client::nsql and Client::nsql_generate_sql, wrapping the runtime's /v1/nsql text-to-SQL endpoint, plus the NsqlRequest / NsqlResponse types in a new nsql module.

Why

Text-to-SQL is reachable from spice.js and from no other SDK. A Rust caller who wanted it had to hand-roll the HTTP request — including knowing to send Accept: application/vnd.spiceai.nsql.v1+json, without which the runtime falls back to a bare array of rows and the generated SQL is lost.

Two methods rather than one, because the generated SQL is useful on its own:

  • nsql generates, runs, and returns the rows together with the SQL that produced them.
  • nsql_generate_sql stops after generation. That lets a caller inspect or edit the query first, and — since /v1/nsql results arrive as decoded JSON, where Arrow types are flattened to JSON's — run it through sql() instead when Arrow types matter.

NsqlRequest follows the existing SearchRequest shape: new() plus with_* builders taking mut self. Errors are a typed NsqlError enum; a missing or ambiguous model is the most common failure and the runtime explains it in the response body, so that body is surfaced rather than collapsed into a status code.

Part of aligning capability across the SDKs; /v1/search and /v1/status landed here recently and NSQL was the remaining gap against the runtime's client-facing surface.

Verification

  • cargo build, cargo fmt --all --check
  • cargo clippy --all-features --all-targets — no new warnings (the 5 remaining are pre-existing, in tests/client_test.rs)
  • cargo test --lib — 235 pass, including 12 new NSQL cases: request serialization and default-omission, response decoding with both a simple and a parameterized Arrow type, empty result set (the runtime sends schema: {}), and wiremock coverage asserting each media type, the surfaced error body, pre-send validation, and the missing-http_url path
  • cargo test --doc — 39 pass, including the two new README examples
  • Integration tests — not run; the 7 test_local_* cases in tests/client_test.rs need spice run on the default ports and the spice CLI is not available in this environment.

Text-to-SQL was reachable from spice.js but from no other SDK, so Rust callers
had to hand-roll the HTTP call - including knowing to ask for
application/vnd.spiceai.nsql.v1+json, without which the runtime returns a bare
array of rows and drops the generated SQL.

nsql runs the generated query and returns the rows alongside the SQL.
nsql_generate_sql stops after generation, so the query can be inspected,
edited, or run through sql() to get Arrow-typed results instead of decoded
JSON.
@sgrebnov
sgrebnov merged commit 51f86e0 into spiceai:trunk Aug 19, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants