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/lcIvnTDOWnaa3e7vG1dbyjQH2vT4XBIg1SxmUQ7WXIlOW0Q+H8/UHZiO0kP24B7uzw5FEVSHz9S1Aq9mDnsD3Fwe4mjCBNysZWZl0ZjHz+TJis8gdAJmCAVSi2BXijOWQxa+NwK1VFCz3IxI/D04jvedAa3l/DmenB7+RaecrLL7oN+0Pdz6YB0khmpPcwq6w4EsHrQg9xJPastw8ZyuVzZ3B+QA+m77IYaBqXbeEpgsgQ/J3AZxXIqKYHUJKSCucpGAnIadB4/xDFl/hHmJBKybEcbD448eAOPIsuUjAWHcOie1GMXIzQZu5FGXyTYx8w4P9buSWGEmbAiJU+WwV6hFilhH0sPGKFktEs/uJ0EPs3U2FR4MGVkllxmtKMIjCYWHjSD+eaMPoA3CU1FrvzbqL260EnXZTImIbscW3dx9EvYsaXnnhSLOJ2HsVscgLHVv0wJqQ+6u+rwLJUCo9USLPnc6hBsnYidLATsGTdLT7m0lGDf25widPGcUoH9FfplxkA5b6WeYVGMSmVy/qNJlqzRBuuuXISJSZacplnNYLjehIIRxkZ70p4tbIPHsp0IzOQbxb4V6xBLY6MIM8up95JcCEl44ci7evsQhbWC/epcKd4hPaVuzwm3s38tUnKc47VRPpUTaaYIptakXbiYgkml95REIJSqFYUlyB0lXbYasN71t49sTM411cry8IYNMQtDOitQpdFd+FTSrA8PqJ/UA7KvEpbv9LW3yr2BCUFs9IJsKEntDbtm6+Xhx3zMMWkxUZyLja+JMYqE3nH255z8nOwaOt7NFS11rPIkeAjnDbR48f9+VCYpFkWEXnpFNes4OnoJDjiiCgb8zB1jTuBNBqcQ586blKwLVWC8UOCEIoebHDGQ+Mo5y/qoCTbEsDlo4ajgoNrFFARluwh0O+71dqumrtFNE3R5HJNz01ypnymXNd3XNC+a0AxXuEZhLLlTHh3/enKKEQY4xiUc/aPTXq/XK6Jt5Xe/vf+9t6N8zNrFqIhwqy3tDa+utk1Q+KCh8RucX56f3UPDdQSDr1dvGl7ftnf8cXdzBXU22ouf726+foGPfzUNtjVu7j6d37HGthf4dD44a+teXlxd3MNpW4hbZ3+t07cAaTPWmudxbHLO83GzC08lqaR1czVTUvJxXEE7WBc7dzpmLfanQjlmrYx9SGFv/e3GxiYUuBp0ONmVg2Z22w4utH938pP2mR+hVP5LDkYYaIffQyH4MIDG/we9w6L9zNmwpbG5IkpFDixCNzjZV+8XeiGUTKC6SqExnfx4qe+rpatwbTDrwsw0NblOMMRzuj8eT1ZzJyS7IAtkrbHtUOrR47uDuDZVU8usSfKYknBhlmNA2WpLiFLyc7Me2MKs5ufYx8PF0WE1vZVhlQWQW87t3Pusf3ioTCzU3Djff98LhGif65KXIaEFKZOlpH11wC6cGT2Vs9wSPEs/h8dOhy0+djHQh+LcSr8M/kQmx38Tf494jdNwV09A53Xxrm+PzW27vn82gldvlIIn0KkJeFZXms21lyntvbRDV0mgVlEyJu1CFOvJNhPxnDrHXQZFJqQ9j9u2vVJEyLCWho+6J6WIs5AK3TB2v/Om2A5rVVPl/0fLDz5aqgpqFFgRlSxfVaUwxMURN1wuhlGEzHcWrlYT4eirVUXB4opuw1GEC2Fl2ZqH3HGrhw2zOTAZz8pkde7ZNaurPAwN2+2GG2+5Y/NSel131KjkLzeDe4xwUr0RGC/mtHjmAV48Yx/Da413h6koyFa4Thv2sbTJv38A+kAuGQ==
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/lcIvnTDOWnaa3e7vG1dbyjQH2vT4XBIg1SxmUQ7WXIlOW0Q+H8/UHZiO0kP24B7uzw5FEVSHz9S1Aq9mDnsD3Fwe4mjCBNysZWZl0ZjHz+TJis8gdAJmCAVSi2BXijOWQxa+NwK1VFCz3IxI/D04jvedAa3l/DmenB7+RaecrLL7oN+0Pdz6YB0khmpPcwq6w4EsHrQg9xJPastw8ZyuVzZ3B+QA+m77IYaBqXbeEpgsgQ/J3AZxXIqKYHUJKSCucpGAnIadB4/xDFl/hHmJBKybEcbD448eAOPIsuUjAWHcOie1GMXIzQZu5FGXyTYx8w4P9buSWGEmbAiJU+WwV6hFilhH0sPGKFktEs/uJ0EPs3U2FR4MGVkllxmtKMIjCYWHjSD+eaMPoA3CU1FrvzbqL260EnXZTImIbscW3dx9EvYsaXnnhSLOJ2HsVscgLHVv0wJqQ+6u+rwLJUCo9USLPnc6hBsnYidLATsGTdLT7m0lGDf25widPGcUoH9FfplxkA5b6WeYVGMSmVy/qNJlqzRBuuuXISJSZacplnNYLjehIIRxkZ70p4tbIPHsp0IzOQbxb4V6xBLY6MIM8up95JcCEl44ci7evsQhbWC/epcKd4hPaVuzwm3s38tUnKc47VRPpUTaaYIptakXbiYgkml95REIJSqFYUlyB0lXbYasN71t49sTM411cry8IYNMQtDOitQpdFd+FTSrA8PqJ/UA7KvEpbv9LW3yr2BCUFs9IJsKEntDbtm6+Xhx3zMMWkxUZyLja+JMYqE3nH255z8nOwaOt7NFS11rPIkeAjnDbR48f9+VCYpFkWEXnpFNes4OnoJDjiiCgb8zB1jTuBNBqcQ586blKwLVWC8UOCEIoebHDGQ+Mo5y/qoCTbEsDlo4ajgoNrFFARluwh0O+71dqumrtFNE3R5HJNz01ypnymXNd3XNC+a0AxXuEZhLLlTHh3/enKKEQY4xiUc/aPTXq/XK6Jt5Xe/vf+9t6N8zNrFqIhwqy3tDa+utk1Q+KCh8RucX56f3UPDdQSDr1dvGl7ftnf8cXdzBXU22ouf726+foGPfzUNtjVu7j6d37HGthf4dD44a+teXlxd3MNpW4hbZ3+t07cAaTPWmudxbHLO83GzC08lqaR1czVTUvJxXEE7WBc7dzpmLfanQjlmrYx9SGFv/e3GxiYUuBp0ONmVg2Z22w4utH938pP2mR+hVP5LDkYYaIffQyH4MIDG/we9w6L9zNmwpbG5IkpFDixCNzjZV+8XeiGUTKC6SqExnfx4qe+rpatwbTDrwsw0NblOMMRzuj8eT1ZzJyS7IAtkrbHtUOrR47uDuDZVU8usSfKYknBhlmNA2WpLiFLyc7Me2MKs5ufYx8PF0WE1vZVhlQWQW87t3Pusf3ioTCzU3Djff98LhGif65KXIaEFKZOlpH11wC6cGT2Vs9wSPEs/h8dOhy0+djHQh+LcSr8M/kQmx38Tf494jdNwV09A53Xxrm+PzW27vn82gldvlIIn0KkJeFZXms21lyntvbRDV0mgVlEyJu1CFOvJNhPxnDrHXQZFJqQ9j9u2vVJEyLCWho+6J6WIs5AK3TB2v/Om2A5rVVPl/0fLDz5aqgpqFFgRlSxfVaUwxMURN1wuhlGEzHcWrlYT4eirVUXB4opuw1GEC2Fl2ZqH3HGrhw2zOTAZz8pkde7ZNaurPAwN2+2GG2+5Y/NSel131KjkLzeDe4xwUr0RGC/mtHjmAV48Yx/Da413h6koyFa4Thv2sbTJv38A+kAuGQ==
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