v1

latestOpenAPI 3.1.02026-07-1730321418.0 KB

SQL

Text-to-SQL (NSQL)

Generate and optionally execute a natural-language text-to-SQL (NSQL) query.

This endpoint generates a SQL query using a natural language query (NSQL) and optionally executes it. The SQL query is generated by the specified model and executed if the Accept header is not set to application/sql. When stream is true, the response is streamed as Server-Sent Events (SSE).

post/v1/nsql

Headers

Acceptstring required

The format of the response, one of 'application/json' (default), 'application/vnd.spiceai.nsql.v1+json', 'application/sql', 'text/csv' or 'text/plain'. 'application/sql' will only return the SQL query generated by the model.

Request body

datasetsstring[] nullable

Names of datasets to sample from when constructing model context; this is a sampling hint and does not restrict which tables queries can target. If omitted, all datasets are used.

modelstring nullable

The name of the model to use for SQL generation. If omitted, Spice defaults to the only compatible LLM model configured in the Spicepod.

prompt_cache_keystring nullable

Stable prompt-cache key forwarded to the configured NSQL model for provider-specific cache handling.

querystring required

The natural language query to be converted into SQL

sample_data_enabledboolean

Whether sample data is included in the context for SQL generation. Default: false

streamboolean

If true, streams the response instead of waiting for completion

Response

SQL query executed successfully

{"stackTrail":"paths:/v1/nsql:post:responses:200:content:application/json:schema:items","oasType":"schema","type":"unknown"}