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