1---
2id: post-sql
3title: "SQL Query"
4description: "Execute a SQL query and return the results."
5sidebar_label: "SQL Query"
6hide_title: true
7hide_table_of_contents: true
8api: eJztWG1v2zYQ/isEvyRFFEUvfpO+pVm6BUiXNnEGDEngstLZ5kaTCkk5MTz/9+Eou5FsNX3bsBaYvsS5O97dc3c88riklk0MTW/o1dtzeufRHEymeWG5kjSlp4+QlRYII1dvz8l9CXpBmMyJBltqSewUiAZTCmv8W3krh1NuCMi8UFxawoRQD4aUBrQhVhFYK9uo4mBIzjVkVizIWKsZYZL8Mhy+IRruSzDWJ8Mp1CxzQwygYkMKwbgkFh4t4Rs/3BryXuULn3pUFaAZwjjLaUoLZezI3Avq0YJpNgMLGmEvqWQzoCk9zjIoLPUoR9xTYDlouh0OdGes9IxZosYb9IWSBjyiJCBxjxWF4JmzfPSHUXKP7OcwZqWwL7wmdy5z3xQ8A8Z9cy/8eXjgFnhkD4EdZWa+R5Re/+cQ7yEyRMo15DS1ugSPmmwKM0bTJbWLArEYq7mc0NXqrhIGY1+qfIESTTxPoX1KD/VopqQFaVF+Gw3SPthbeRQe2awQ4Mj3AlWenp+eDEk6VoockJAcX2GcRkyaBxfQevSXdKwUTTvharXy6BPKhpFtUDWbG2NsPtm3yjIxYjNVSgy0I/HiiZDh3/3whUcKZgzICeiRo5FXlxevyWwxsuy9APLz5cX1G/Ly9x2xi8ufTi/bGMdXJ+T87PXZkMQUcTTT4whVjTjEURA8l4d1EnJiyiwDY8alEIsvSMkmWkxrhuu4hRnaXdXjdrOkx7/9vL/B7NcCRdPYD/pR1E2SfhgnvX4Se1vC9UDTNOr6cdQfhL0kTjrdXjfqevTk4vrX4f6ZtL3OfvgCdYadXhdz34gcTYOV97wrcT+MelE0GHR6gyDo9j/hS8+Pgm4UB51Ot9PvJEmvxZcoHAz6cdLiTfgpb/phP4yDKAzjKAkG3c4nvEn8bhT0ukkSB0kcxEGnxZtO0A2DuMWZaHW32ROZmX/2jrj9KIBb6m0z6/469pZ7jrbl2S29lbsl0lIFVc4DlN7JYkuiNmkJccFOoFtiuY5cRL+uddxKUvsODp/5vozZLn3QtPcXeS5RbfxmrpzATrYcdSdfaO6/RrtTMQ3ubvXUl2Id1aUDsvt9BwC3i7wBcKfe68yq8p8I4fcJcHtTNgDu7M8as9qpdenvASC2g8+4jT1z4dHqYdOt4/otbMxB5M3L5ccOFY/mzLLRuk+9EorZXod6VJZCoDBNx0wY8GjOMzviOU2DzW8zUjoHd89wMnh4tZprnEr/jsHtY61pxdG/2cb2CfnP2cCDFnX9fzH6US5Gbl7otN2kz+ScCZ7XhkalyYwJnNogJ1wWpW1ep7/i7nCqtdJEA8u5nFRmUsLXlq+Hrw4HxODYJTOgztVuu6sWtGSCGNBz0ARQ6zf7di3hsYDMOrAtBojKslJj9VdRnIGdqs2E7OYzO6UpPZqHR9W4XC2u2lmpccSbWlukR0dCZUxMlbHpIEiCnVn5HNkkhzkIVcxwbK80+eREyTGflBrIA7dT8u7wEDW+8ynOqwayUnO7cPZYwUd/Av6+Qx6XY+Xgc+uw6lJaPoPWMd218pw8iQiegTSucW/aZMGyKRxGPjrPc5CWjznoJmflUYRfKQ79MPSDw1IaV9jIxLDNmKypxdJ7izWx7dfyKbU/8sPKuvhqtbnyqspYrqvnhs5DrJx7gS9KWCJIWy7fMwPXWqxWSHaWMbMenTPNq6Z9g714/fiCBeCST0+qsB0O0TKKi9LNuNuDMLapasWH15yPy97Vav/NxdWQevT9+pFkpnJXXuwBX1vYA02pe1DC1W6Id7QlFUxOSjZB2Uonfn8D+MzJ4g==
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={"SQL Query"}
27>
28</Heading>
29
30<MethodEndpoint
31 method={"post"}
32 path={"/v1/sql"}
33 context={"endpoint"}
34>
35
36</MethodEndpoint>
37
38
39
40Execute a SQL query and return the results.
41
42This endpoint executes SQL queries directly from an HTTP request. The SQL query is sent as plain text in the request body.
43
44<Heading
45 id={"request"}
46 as={"h2"}
47 className={"openapi-tabs__heading"}
48 children={"Request"}
49>
50</Heading>
51
52<ParamsDetails
53 parameters={[{"name":"Accept","in":"header","description":"The format of the response, one of 'application/json' (default), 'application/vnd.spiceai.sql.v1+json', 'text/csv' or 'text/plain'.","required":true,"schema":{"type":"string"}}]}
54>
55
56</ParamsDetails>
57
58<RequestSchema
59 title={"Body"}
60 body={{"description":"SQL query to execute","content":{"application/json":{"schema":{},"example":{"sql":"SELECT :foo + 1 AS the_answer","parameters":{"foo":41}}},"text/plain":{"schema":{"type":"string"},"example":"SELECT avg(total_amount), avg(tip_amount), count(1), passenger_count FROM my_table GROUP BY passenger_count ORDER BY passenger_count ASC LIMIT 3"}},"required":true}}
61>
62
63</RequestSchema>
64
65<StatusCodes
66 id={undefined}
67 label={undefined}
68 responses={{"200":{"description":"SQL query executed successfully","content":{"application/json":{"schema":{"type":"array","items":{}},"example":[{"AVG(my_table.tip_amount)":3.072259971396793,"AVG(my_table.total_amount)":25.327816939456525,"COUNT(Int64(1))":31465,"passenger_count":0},{"AVG(my_table.tip_amount)":3.3712622884680057,"AVG(my_table.total_amount)":26.205230445474996,"COUNT(Int64(1))":2188739,"passenger_count":1},{"AVG(my_table.tip_amount)":3.7171302113290854,"AVG(my_table.total_amount)":29.520659930930304,"COUNT(Int64(1))":405103,"passenger_count":2}]},"text/csv":{"schema":{"type":"string"},"example":"\"AVG(my_table.tip_amount)\",\"AVG(my_table.total_amount)\",\"COUNT(Int64(1))\",\"passenger_count\"\n3.072259971396793,25.327816939456525,31465,0\n3.3712622884680057,26.205230445474996,2188739,1\n3.7171302113290854,29.520659930930304,405103,2"},"text/plain":{"schema":{"type":"string"},"example":"\n +----------------------------+----------------------------+----------------+---------------------+\n | \"AVG(my_table.tip_amount)\" | \"AVG(my_table.total_amount)\" | \"COUNT(Int64(1))\" | \"passenger_count\" |\n +----------------------------+----------------------------+----------------+---------------------+\n | 3.072259971396793 | 25.327816939456525 | 31465 | 0 |\n +----------------------------+----------------------------+----------------+---------------------+\n | 3.3712622884680057 | 26.205230445474996 | 2188739 | 1 |\n +----------------------------+----------------------------+----------------+---------------------+\n | 3.7171302113290854 | 29.520659930930304 | 405103 | 2 |\n +----------------------------+----------------------------+----------------+---------------------+"},"application/vnd.spiceai.sql.v1+json":{"schema":{},"example":{"row_count":3,"schema":{"fields":[{"name":"AVG(my_table.tip_amount)","data_type":"Float64","nullable":false,"dict_id":0,"dict_is_ordered":false},{"name":"AVG(my_table.total_amount)","data_type":"Float64","nullable":false,"dict_id":0,"dict_is_ordered":false},{"name":"COUNT(Int64(1))","data_type":"Int64","nullable":false,"dict_id":0,"dict_is_ordered":false},{"name":"passenger_count","data_type":"Int64","nullable":false,"dict_id":0,"dict_is_ordered":false}]},"data":[{"AVG(my_table.tip_amount)":3.072259971396793,"AVG(my_table.total_amount)":25.327816939456525,"COUNT(Int64(1))":31465,"passenger_count":0},{"AVG(my_table.tip_amount)":3.3712622884680057,"AVG(my_table.total_amount)":26.205230445474996,"COUNT(Int64(1))":2188739,"passenger_count":1},{"AVG(my_table.tip_amount)":3.7171302113290854,"AVG(my_table.total_amount)":29.520659930930304,"COUNT(Int64(1))":405103,"passenger_count":2}]}}}},"400":{"description":"Invalid SQL query or malformed input","content":{"text/plain":{"schema":{"type":"string"},"example":"Error reading query: invalid UTF-8 sequence"}}},"500":{"description":"Internal server error","content":{"text/plain":{"schema":{"type":"string"},"example":"Unexpected internal server error occurred"}}}}}69>
70
71</StatusCodes>
72
73
74
1---
2id: post-sql
3title: "SQL Query"
4description: "Execute a SQL query and return the results."
5sidebar_label: "SQL Query"
6hide_title: true
7hide_table_of_contents: true
8api: eJztWG1v2zYQ/isEvyRFFEUvfpO+pVm6BUiXNnEGDEngstLZ5kaTCkk5MTz/9+Eou5FsNX3bsBaYvsS5O97dc3c88riklk0MTW/o1dtzeufRHEymeWG5kjSlp4+QlRYII1dvz8l9CXpBmMyJBltqSewUiAZTCmv8W3krh1NuCMi8UFxawoRQD4aUBrQhVhFYK9uo4mBIzjVkVizIWKsZYZL8Mhy+IRruSzDWJ8Mp1CxzQwygYkMKwbgkFh4t4Rs/3BryXuULn3pUFaAZwjjLaUoLZezI3Avq0YJpNgMLGmEvqWQzoCk9zjIoLPUoR9xTYDlouh0OdGes9IxZosYb9IWSBjyiJCBxjxWF4JmzfPSHUXKP7OcwZqWwL7wmdy5z3xQ8A8Z9cy/8eXjgFnhkD4EdZWa+R5Re/+cQ7yEyRMo15DS1ugSPmmwKM0bTJbWLArEYq7mc0NXqrhIGY1+qfIESTTxPoX1KD/VopqQFaVF+Gw3SPthbeRQe2awQ4Mj3AlWenp+eDEk6VoockJAcX2GcRkyaBxfQevSXdKwUTTvharXy6BPKhpFtUDWbG2NsPtm3yjIxYjNVSgy0I/HiiZDh3/3whUcKZgzICeiRo5FXlxevyWwxsuy9APLz5cX1G/Ly9x2xi8ufTi/bGMdXJ+T87PXZkMQUcTTT4whVjTjEURA8l4d1EnJiyiwDY8alEIsvSMkmWkxrhuu4hRnaXdXjdrOkx7/9vL/B7NcCRdPYD/pR1E2SfhgnvX4Se1vC9UDTNOr6cdQfhL0kTjrdXjfqevTk4vrX4f6ZtL3OfvgCdYadXhdz34gcTYOV97wrcT+MelE0GHR6gyDo9j/hS8+Pgm4UB51Ot9PvJEmvxZcoHAz6cdLiTfgpb/phP4yDKAzjKAkG3c4nvEn8bhT0ukkSB0kcxEGnxZtO0A2DuMWZaHW32ROZmX/2jrj9KIBb6m0z6/469pZ7jrbl2S29lbsl0lIFVc4DlN7JYkuiNmkJccFOoFtiuY5cRL+uddxKUvsODp/5vozZLn3QtPcXeS5RbfxmrpzATrYcdSdfaO6/RrtTMQ3ubvXUl2Id1aUDsvt9BwC3i7wBcKfe68yq8p8I4fcJcHtTNgDu7M8as9qpdenvASC2g8+4jT1z4dHqYdOt4/otbMxB5M3L5ccOFY/mzLLRuk+9EorZXod6VJZCoDBNx0wY8GjOMzviOU2DzW8zUjoHd89wMnh4tZprnEr/jsHtY61pxdG/2cb2CfnP2cCDFnX9fzH6US5Gbl7otN2kz+ScCZ7XhkalyYwJnNogJ1wWpW1ep7/i7nCqtdJEA8u5nFRmUsLXlq+Hrw4HxODYJTOgztVuu6sWtGSCGNBz0ARQ6zf7di3hsYDMOrAtBojKslJj9VdRnIGdqs2E7OYzO6UpPZqHR9W4XC2u2lmpccSbWlukR0dCZUxMlbHpIEiCnVn5HNkkhzkIVcxwbK80+eREyTGflBrIA7dT8u7wEDW+8ynOqwayUnO7cPZYwUd/Av6+Qx6XY+Xgc+uw6lJaPoPWMd218pw8iQiegTSucW/aZMGyKRxGPjrPc5CWjznoJmflUYRfKQ79MPSDw1IaV9jIxLDNmKypxdJ7izWx7dfyKbU/8sPKuvhqtbnyqspYrqvnhs5DrJx7gS9KWCJIWy7fMwPXWqxWSHaWMbMenTPNq6Z9g714/fiCBeCST0+qsB0O0TKKi9LNuNuDMLapasWH15yPy97Vav/NxdWQevT9+pFkpnJXXuwBX1vYA02pe1DC1W6Id7QlFUxOSjZB2Uonfn8D+MzJ4g==
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={"SQL Query"}
27>
28</Heading>
29
30<MethodEndpoint
31 method={"post"}
32 path={"/v1/sql"}
33 context={"endpoint"}
34>
35
36</MethodEndpoint>
37
38
39
40Execute a SQL query and return the results.
41
42This endpoint executes SQL queries directly from an HTTP request. The SQL query is sent as plain text in the request body.
43
44<Heading
45 id={"request"}
46 as={"h2"}
47 className={"openapi-tabs__heading"}
48 children={"Request"}
49>
50</Heading>
51
52<ParamsDetails
53 parameters={[{"name":"Accept","in":"header","description":"The format of the response, one of 'application/json' (default), 'application/vnd.spiceai.sql.v1+json', 'text/csv' or 'text/plain'.","required":true,"schema":{"type":"string"}}]}
54>
55
56</ParamsDetails>
57
58<RequestSchema
59 title={"Body"}
60 body={{"description":"SQL query to execute","content":{"application/json":{"schema":{},"example":{"sql":"SELECT :foo + 1 AS the_answer","parameters":{"foo":41}}},"text/plain":{"schema":{"type":"string"},"example":"SELECT avg(total_amount), avg(tip_amount), count(1), passenger_count FROM my_table GROUP BY passenger_count ORDER BY passenger_count ASC LIMIT 3"}},"required":true}}
61>
62
63</RequestSchema>
64
65<StatusCodes
66 id={undefined}
67 label={undefined}
68 responses={{"200":{"description":"SQL query executed successfully","content":{"application/json":{"schema":{"type":"array","items":{}},"example":[{"AVG(my_table.tip_amount)":3.072259971396793,"AVG(my_table.total_amount)":25.327816939456525,"COUNT(Int64(1))":31465,"passenger_count":0},{"AVG(my_table.tip_amount)":3.3712622884680057,"AVG(my_table.total_amount)":26.205230445474996,"COUNT(Int64(1))":2188739,"passenger_count":1},{"AVG(my_table.tip_amount)":3.7171302113290854,"AVG(my_table.total_amount)":29.520659930930304,"COUNT(Int64(1))":405103,"passenger_count":2}]},"text/csv":{"schema":{"type":"string"},"example":"\"AVG(my_table.tip_amount)\",\"AVG(my_table.total_amount)\",\"COUNT(Int64(1))\",\"passenger_count\"\n3.072259971396793,25.327816939456525,31465,0\n3.3712622884680057,26.205230445474996,2188739,1\n3.7171302113290854,29.520659930930304,405103,2"},"text/plain":{"schema":{"type":"string"},"example":"\n +----------------------------+----------------------------+----------------+---------------------+\n | \"AVG(my_table.tip_amount)\" | \"AVG(my_table.total_amount)\" | \"COUNT(Int64(1))\" | \"passenger_count\" |\n +----------------------------+----------------------------+----------------+---------------------+\n | 3.072259971396793 | 25.327816939456525 | 31465 | 0 |\n +----------------------------+----------------------------+----------------+---------------------+\n | 3.3712622884680057 | 26.205230445474996 | 2188739 | 1 |\n +----------------------------+----------------------------+----------------+---------------------+\n | 3.7171302113290854 | 29.520659930930304 | 405103 | 2 |\n +----------------------------+----------------------------+----------------+---------------------+"},"application/vnd.spiceai.sql.v1+json":{"schema":{},"example":{"row_count":3,"schema":{"fields":[{"name":"AVG(my_table.tip_amount)","data_type":"Float64","nullable":false,"dict_id":0,"dict_is_ordered":false},{"name":"AVG(my_table.total_amount)","data_type":"Float64","nullable":false,"dict_id":0,"dict_is_ordered":false},{"name":"COUNT(Int64(1))","data_type":"Int64","nullable":false,"dict_id":0,"dict_is_ordered":false},{"name":"passenger_count","data_type":"Int64","nullable":false,"dict_id":0,"dict_is_ordered":false}]},"data":[{"AVG(my_table.tip_amount)":3.072259971396793,"AVG(my_table.total_amount)":25.327816939456525,"COUNT(Int64(1))":31465,"passenger_count":0},{"AVG(my_table.tip_amount)":3.3712622884680057,"AVG(my_table.total_amount)":26.205230445474996,"COUNT(Int64(1))":2188739,"passenger_count":1},{"AVG(my_table.tip_amount)":3.7171302113290854,"AVG(my_table.total_amount)":29.520659930930304,"COUNT(Int64(1))":405103,"passenger_count":2}]}}}},"400":{"description":"Invalid SQL query or malformed input","content":{"text/plain":{"schema":{"type":"string"},"example":"Error reading query: invalid UTF-8 sequence"}}},"500":{"description":"Internal server error","content":{"text/plain":{"schema":{"type":"string"},"example":"Unexpected internal server error occurred"}}}}}69>
70
71</StatusCodes>
72
73
74