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: eJztV99v2zgM/lcIvnTDOW7aW3e7vG1dbyjQH1vT4nBIg1SxmUSbIrmSnDYI/L8PlJ3YTtLDNuDeLk+ORJEU+X0ktUIvpg57A+x/ucBhhCm5xMrMS6Oxh59IkxWeQOgUTFgVSi2BninJeRm08LkVqqOEnuZiSuDp2Xe86fS/XMCrq/6Xi9fwmJNdxvf6Xt/OpAPSaWak9jCttDsQwOJBDnIn9bTWDBvN5Xalc79DDqSP2Qw1FEq3sZTCeAl+RuAySuREUgpzk5IK6iodKchJkHl4nySU+QeYkUjJsh5tPDjy4A08iCxTMhHswqF7VA8xRmgyNiONPk+xh5lxfqTdo8IIM2HFnDxZDvYKtZgT9rC0gBFKjnZpB7eTwLeZGDsXHkzpmSWXGe0oAqOJFw+aznx1Rh/Aq5QmIlf+ddTeXeg0dplMSMiYfYsXR7+FE1ty7lHxEqfzMHGLAzC2+pcpIfVBvCsOT1IpMFotwZLPrQ7O1onYyUKIPcfN0mMuLaXY8zanCF0yo7nA3gr9MuNAOW+lnmJRDEthcv6DSZcs0Q7WTbkJY5MuOU3TGsFwtXEFI0yM9qQ9a9gOHq/teGDGXynxLV8HWCobRphZTr2X5IJLwgtH3tXHByisFWxX50rxCelp7vbccDv7V2JOjnO8Vsq3cmKeKYKJNfMYzidg5tJ7SiMQStWCwhLkjtKYtYZY79rbBzYG5xpqJT28YUWMwpDOKqjS6Bg+ljDrwT3qR3WPbKsMyw/a2styb2BMkBi9IBsoqb1h06y9vPyIrzkiLcaKc7GxNTZGkdA7xv6ekZ+RXYeOTzOjpU5UngYL4b4BFs/+36/KIMWiiNBLr6hGHXtHz8EAe1SFAT9xxZgReJPBCSS582ZO1gUWGC8UOKHI4SZHHEh84Z4lP2qADTAcDlI4LNipNpnCQlkuAtyOu91d1tQc3RRBlycJOTfJlfoVuqzhvoZ50QzNYIXrKIwkV8qj49/fnGCEIRyjMhy9o5Nut9stom3ht3+8+7O7I3zM0sWwiHCrLO11r2bbxim819D49c8uzk5voWE6gv7d5auG1dftE3/dXF9CnY325qeb67vP8OGfpsK2xPXNx7Mblti2Ah/P+qdt2Yvzy/NbOGkv4tbdX6r0rYC0EWvN0ygxOef5uFmFJ5JU2upczZSUeBxVoe2vyc6VjlGLvYlQjlErEx9S2F1/u5GxKQWsBhlOdmWgmd22gXPt3775Rf2Mj0CV/xKDEQbY4Y9ACN73ofH/Xu+gaD9yNmhpHK6AUoEDi1AN3uzj+7leCCVTqFopNKaTn6f6Pi5dhrbBqAsz08TkOsXgz8l+fzxZzZWQ7IIskLXGtl2pR48fduLKVEUtsybNE0pDwyzHgLLUliGak5+Z9cAWZjU/wx4eLo4Oq+mtdKskQG45tzPvs97hoTKJUDPjfO9dNwCifa8L3oaUFqRMNiftqwvGcGr0RE5zS/Ak/QweOh3W+BBjgA8luZV+GeyJTI6+EX8PeY/TcFNPQGc1eeumgHf6mzZPGm6XGfUg1OIoDB51j9n05HWX2iy82HcKnlMnJkS9anw2117OaW9rD7UnhVpEyYS0C76u599MJDPqHMccOpmS9jyU2/ZOESEHv1R8FL+Nu51cOx+oX0QhaXOhG1pvd54g2/6tamT9/8b5yTdORbgGH4uoJMWqYs4AF0dcn5k7wwiZHry4Wo2FozurioKXK9wNhhEuhJVlJR9wga7eQQz+AHw8LZPVYTgji6s8zBjb1YnrdHli87B6WXbYIP7n6/4tRjiunhQcLwa3eOJ5XzxhD8Pjjk+HISqsrXCdNuxhqZN/3wFVRD7/
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`.
44
45<Heading
46 id={"request"}
47 as={"h2"}
48 className={"openapi-tabs__heading"}
49 children={"Request"}
50>
51</Heading>
52
53<ParamsDetails
54 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"}}]}
55>
56
57</ParamsDetails>
58
59<RequestSchema
60 title={"Body"}
61 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. 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"}},"title":"Request"},"example":{"query":"Get the top 5 customers by total sales","model":"nql","sample_data_enabled":true,"datasets":["sales_data"]}}},"required":true}}
62>
63
64</RequestSchema>
65
66<StatusCodes
67 id={undefined}
68 label={undefined}
69 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"}}}},"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"}}}}}
70>
71
72</StatusCodes>
73
74
75
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: eJztV99v2zgM/lcIvnTDOW7aW3e7vG1dbyjQH1vT4nBIg1SxmUSbIrmSnDYI/L8PlJ3YTtLDNuDeLk+ORJEU+X0ktUIvpg57A+x/ucBhhCm5xMrMS6Oxh59IkxWeQOgUTFgVSi2BninJeRm08LkVqqOEnuZiSuDp2Xe86fS/XMCrq/6Xi9fwmJNdxvf6Xt/OpAPSaWak9jCttDsQwOJBDnIn9bTWDBvN5Xalc79DDqSP2Qw1FEq3sZTCeAl+RuAySuREUgpzk5IK6iodKchJkHl4nySU+QeYkUjJsh5tPDjy4A08iCxTMhHswqF7VA8xRmgyNiONPk+xh5lxfqTdo8IIM2HFnDxZDvYKtZgT9rC0gBFKjnZpB7eTwLeZGDsXHkzpmSWXGe0oAqOJFw+aznx1Rh/Aq5QmIlf+ddTeXeg0dplMSMiYfYsXR7+FE1ty7lHxEqfzMHGLAzC2+pcpIfVBvCsOT1IpMFotwZLPrQ7O1onYyUKIPcfN0mMuLaXY8zanCF0yo7nA3gr9MuNAOW+lnmJRDEthcv6DSZcs0Q7WTbkJY5MuOU3TGsFwtXEFI0yM9qQ9a9gOHq/teGDGXynxLV8HWCobRphZTr2X5IJLwgtH3tXHByisFWxX50rxCelp7vbccDv7V2JOjnO8Vsq3cmKeKYKJNfMYzidg5tJ7SiMQStWCwhLkjtKYtYZY79rbBzYG5xpqJT28YUWMwpDOKqjS6Bg+ljDrwT3qR3WPbKsMyw/a2styb2BMkBi9IBsoqb1h06y9vPyIrzkiLcaKc7GxNTZGkdA7xv6ekZ+RXYeOTzOjpU5UngYL4b4BFs/+36/KIMWiiNBLr6hGHXtHz8EAe1SFAT9xxZgReJPBCSS582ZO1gUWGC8UOKHI4SZHHEh84Z4lP2qADTAcDlI4LNipNpnCQlkuAtyOu91d1tQc3RRBlycJOTfJlfoVuqzhvoZ50QzNYIXrKIwkV8qj49/fnGCEIRyjMhy9o5Nut9stom3ht3+8+7O7I3zM0sWwiHCrLO11r2bbxim819D49c8uzk5voWE6gv7d5auG1dftE3/dXF9CnY325qeb67vP8OGfpsK2xPXNx7Mblti2Ah/P+qdt2Yvzy/NbOGkv4tbdX6r0rYC0EWvN0ygxOef5uFmFJ5JU2upczZSUeBxVoe2vyc6VjlGLvYlQjlErEx9S2F1/u5GxKQWsBhlOdmWgmd22gXPt3775Rf2Mj0CV/xKDEQbY4Y9ACN73ofH/Xu+gaD9yNmhpHK6AUoEDi1AN3uzj+7leCCVTqFopNKaTn6f6Pi5dhrbBqAsz08TkOsXgz8l+fzxZzZWQ7IIskLXGtl2pR48fduLKVEUtsybNE0pDwyzHgLLUliGak5+Z9cAWZjU/wx4eLo4Oq+mtdKskQG45tzPvs97hoTKJUDPjfO9dNwCifa8L3oaUFqRMNiftqwvGcGr0RE5zS/Ak/QweOh3W+BBjgA8luZV+GeyJTI6+EX8PeY/TcFNPQGc1eeumgHf6mzZPGm6XGfUg1OIoDB51j9n05HWX2iy82HcKnlMnJkS9anw2117OaW9rD7UnhVpEyYS0C76u599MJDPqHMccOpmS9jyU2/ZOESEHv1R8FL+Nu51cOx+oX0QhaXOhG1pvd54g2/6tamT9/8b5yTdORbgGH4uoJMWqYs4AF0dcn5k7wwiZHry4Wo2FozurioKXK9wNhhEuhJVlJR9wga7eQQz+AHw8LZPVYTgji6s8zBjb1YnrdHli87B6WXbYIP7n6/4tRjiunhQcLwa3eOJ5XzxhD8Pjjk+HISqsrXCdNuxhqZN/3wFVRD7/
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`.
44
45<Heading
46 id={"request"}
47 as={"h2"}
48 className={"openapi-tabs__heading"}
49 children={"Request"}
50>
51</Heading>
52
53<ParamsDetails
54 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"}}]}
55>
56
57</ParamsDetails>
58
59<RequestSchema
60 title={"Body"}
61 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. 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"}},"title":"Request"},"example":{"query":"Get the top 5 customers by total sales","model":"nql","sample_data_enabled":true,"datasets":["sales_data"]}}},"required":true}}
62>
63
64</RequestSchema>
65
66<StatusCodes
67 id={undefined}
68 label={undefined}
69 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"}}}},"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"}}}}}
70>
71
72</StatusCodes>
73
74
75