feat: add nsql and nsql_generate_sql for the runtime's /v1/nsql endpoint - #92
Merged
Conversation
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
approved these changes
Aug 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
Client::nsqlandClient::nsql_generate_sql, wrapping the runtime's/v1/nsqltext-to-SQL endpoint, plus theNsqlRequest/NsqlResponsetypes in a newnsqlmodule.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:
nsqlgenerates, runs, and returns the rows together with the SQL that produced them.nsql_generate_sqlstops after generation. That lets a caller inspect or edit the query first, and — since/v1/nsqlresults arrive as decoded JSON, where Arrow types are flattened to JSON's — run it throughsql()instead when Arrow types matter.NsqlRequestfollows the existingSearchRequestshape:new()pluswith_*builders takingmut self. Errors are a typedNsqlErrorenum; 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/searchand/v1/statuslanded here recently and NSQL was the remaining gap against the runtime's client-facing surface.Verification
cargo build,cargo fmt --all --checkcargo clippy --all-features --all-targets— no new warnings (the 5 remaining are pre-existing, intests/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 sendsschema: {}), and wiremock coverage asserting each media type, the surfaced error body, pre-send validation, and the missing-http_urlpathcargo test --doc— 39 pass, including the two new README examplestest_local_*cases intests/client_test.rsneedspice runon the default ports and thespiceCLI is not available in this environment.