1---
2id: post-nsql
3title: "Text-to-SQL (NSQL)"
4description: "Generate and optionally execute a natural-language text-to-SQL (NSQL) query."
5sidebar_label: "Text-to-SQL (NSQL)"
6hide_title: true
7hide_table_of_contents: true
8api: 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
9sidebar_class_name: "post api-method"
10info_path: docs/api/HTTP/runtime
11custom_edit_url: null
12proxy: http://localhost:8090
13---
14
15import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
16import ParamsDetails from "@theme/ParamsDetails";
17import RequestSchema from "@theme/RequestSchema";
18import StatusCodes from "@theme/StatusCodes";
19import OperationTabs from "@theme/OperationTabs";
20import TabItem from "@theme/TabItem";
21import Heading from "@theme/Heading";
22
23<Heading
24 as={"h1"}
25 className={"openapi__heading"}
26 children={"Text-to-SQL (NSQL)"}
27>
28</Heading>
29
30<MethodEndpoint
31 method={"post"}
32 path={"/v1/nsql"}
33 context={"endpoint"}
34>
35
36</MethodEndpoint>
37
38
39
40Generate and optionally execute a natural-language text-to-SQL (NSQL) query.
41
42This endpoint generates a SQL query using a natural language query (NSQL) and optionally executes it.
43The SQL query is generated by the specified model and executed if the `Accept` header is not set to `application/sql`.
44When `stream` is true, the response is streamed as Server-Sent Events (SSE).
45
46<Heading
47 id={"request"}
48 as={"h2"}
49 className={"openapi-tabs__heading"}
50 children={"Request"}
51>
52</Heading>
53
54<ParamsDetails
55 parameters={[{"name":"Accept","in":"header","description":"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.","required":true,"schema":{"type":"string"}}]}
56>
57
58</ParamsDetails>
59
60<RequestSchema
61 title={"Body"}
62 body={{"description":"Request body to generate an NSQL query","content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"datasets":{"type":["array","null"],"items":{"type":"string"},"description":"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."},"model":{"type":"string","description":"The name of the model to use for SQL generation. Default: \"nql\""},"query":{"type":"string","description":"The natural language query to be converted into SQL"},"sample_data_enabled":{"type":"boolean","description":"Whether sample data is included in the context for SQL generation. Default: true"},"stream":{"type":"boolean","description":"If true, streams the response instead of waiting for completion"}},"title":"Request"},"example":{"query":"Get the top 5 customers by total sales","model":"nql","stream":false,"sample_data_enabled":true,"datasets":["sales_data"]}}},"required":true}}
63>
64
65</RequestSchema>
66
67<StatusCodes
68 id={undefined}
69 label={undefined}
70 responses={{"200":{"description":"SQL query executed successfully","content":{"application/json":{"schema":{"type":"array","items":{}},"example":[{"customer_id":"12345","total_sales":150000},{"customer_id":"67890","total_sales":125000}]},"application/sql":{"schema":{"type":"string"},"example":"\n SELECT customer_id, SUM(total_sales)\n FROM sales_data\n GROUP BY customer_id\n ORDER BY SUM(total_sales) DESC\n LIMIT 5\n "},"application/vnd.spiceai.nsql.v1+json":{"schema":{},"example":{"row_count":2,"schema":{"fields":[{"name":"customer_id","data_type":"String","nullable":false,"dict_id":0,"dict_is_ordered":false},{"name":"total_sales","data_type":"Int64","nullable":false,"dict_id":0,"dict_is_ordered":false}]},"data":[{"customer_id":"12345","total_sales":150000},{"customer_id":"67890","total_sales":125000}],"sql":"SELECT customer_id, SUM(total_sales) AS total_sales\nFROM sales_data\nGROUP BY customer_id\nORDER BY total_sales DESC\nLIMIT 5"}},"text/event-stream":{"schema":{"type":"string"},"example":"data: {\"row_count\": 2, \"schema\": {...}, \"data\": [...], \"sql\": \"SELECT ...\"}\n\n"}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"string"},"example":"Model nsql not found"}}},"500":{"description":"Internal server error","content":{"text/plain":{"schema":{"type":"string"},"example":"No query produced from NSQL model"}}}}}
71>
72
73</StatusCodes>
74
75
76
1---
2id: post-nsql
3title: "Text-to-SQL (NSQL)"
4description: "Generate and optionally execute a natural-language text-to-SQL (NSQL) query."
5sidebar_label: "Text-to-SQL (NSQL)"
6hide_title: true
7hide_table_of_contents: true
8api: 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
9sidebar_class_name: "post api-method"
10info_path: docs/api/HTTP/runtime
11custom_edit_url: null
12proxy: http://localhost:8090
13---
14
15import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
16import ParamsDetails from "@theme/ParamsDetails";
17import RequestSchema from "@theme/RequestSchema";
18import StatusCodes from "@theme/StatusCodes";
19import OperationTabs from "@theme/OperationTabs";
20import TabItem from "@theme/TabItem";
21import Heading from "@theme/Heading";
22
23<Heading
24 as={"h1"}
25 className={"openapi__heading"}
26 children={"Text-to-SQL (NSQL)"}
27>
28</Heading>
29
30<MethodEndpoint
31 method={"post"}
32 path={"/v1/nsql"}
33 context={"endpoint"}
34>
35
36</MethodEndpoint>
37
38
39
40Generate and optionally execute a natural-language text-to-SQL (NSQL) query.
41
42This endpoint generates a SQL query using a natural language query (NSQL) and optionally executes it.
43The SQL query is generated by the specified model and executed if the `Accept` header is not set to `application/sql`.
44When `stream` is true, the response is streamed as Server-Sent Events (SSE).
45
46<Heading
47 id={"request"}
48 as={"h2"}
49 className={"openapi-tabs__heading"}
50 children={"Request"}
51>
52</Heading>
53
54<ParamsDetails
55 parameters={[{"name":"Accept","in":"header","description":"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.","required":true,"schema":{"type":"string"}}]}
56>
57
58</ParamsDetails>
59
60<RequestSchema
61 title={"Body"}
62 body={{"description":"Request body to generate an NSQL query","content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"datasets":{"type":["array","null"],"items":{"type":"string"},"description":"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."},"model":{"type":"string","description":"The name of the model to use for SQL generation. Default: \"nql\""},"query":{"type":"string","description":"The natural language query to be converted into SQL"},"sample_data_enabled":{"type":"boolean","description":"Whether sample data is included in the context for SQL generation. Default: true"},"stream":{"type":"boolean","description":"If true, streams the response instead of waiting for completion"}},"title":"Request"},"example":{"query":"Get the top 5 customers by total sales","model":"nql","stream":false,"sample_data_enabled":true,"datasets":["sales_data"]}}},"required":true}}
63>
64
65</RequestSchema>
66
67<StatusCodes
68 id={undefined}
69 label={undefined}
70 responses={{"200":{"description":"SQL query executed successfully","content":{"application/json":{"schema":{"type":"array","items":{}},"example":[{"customer_id":"12345","total_sales":150000},{"customer_id":"67890","total_sales":125000}]},"application/sql":{"schema":{"type":"string"},"example":"\n SELECT customer_id, SUM(total_sales)\n FROM sales_data\n GROUP BY customer_id\n ORDER BY SUM(total_sales) DESC\n LIMIT 5\n "},"application/vnd.spiceai.nsql.v1+json":{"schema":{},"example":{"row_count":2,"schema":{"fields":[{"name":"customer_id","data_type":"String","nullable":false,"dict_id":0,"dict_is_ordered":false},{"name":"total_sales","data_type":"Int64","nullable":false,"dict_id":0,"dict_is_ordered":false}]},"data":[{"customer_id":"12345","total_sales":150000},{"customer_id":"67890","total_sales":125000}],"sql":"SELECT customer_id, SUM(total_sales) AS total_sales\nFROM sales_data\nGROUP BY customer_id\nORDER BY total_sales DESC\nLIMIT 5"}},"text/event-stream":{"schema":{"type":"string"},"example":"data: {\"row_count\": 2, \"schema\": {...}, \"data\": [...], \"sql\": \"SELECT ...\"}\n\n"}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"string"},"example":"Model nsql not found"}}},"500":{"description":"Internal server error","content":{"text/plain":{"schema":{"type":"string"},"example":"No query produced from NSQL model"}}}}}
71>
72
73</StatusCodes>
74
75
76