vtlim commented on code in PR #14711: URL: https://github.com/apache/druid/pull/14711#discussion_r1283640596
########## docs/api-reference/sql-api.md: ########## @@ -23,167 +23,295 @@ sidebar_label: Druid SQL ~ under the License. --> -> Apache Druid supports two query languages: Druid SQL and [native queries](../querying/querying.md). -> This document describes the SQL language. +Apache Druid supports two query languages: [Druid SQL](../querying/sql.md) and [native queries](../querying/querying.md). This topic describes the SQL language. -You can submit and cancel [Druid SQL](../querying/sql.md) queries using the Druid SQL API. -The Druid SQL API is available at `https://ROUTER:8888/druid/v2/sql`, where `ROUTER` is the IP address of the Druid Router. +In this topic, `http://ROUTER_IP:ROUTER_PORT` is a placeholder for your Router service address and port. Replace it with the information for your deployment. For example, use `http://localhost:8888` for quickstart deployments. -## Submit a query +## Query from Historicals -To use the SQL API to make Druid SQL queries, send your query to the Router using the POST method: -``` -POST https://ROUTER:8888/druid/v2/sql/ -``` +### Submit a query -Submit your query as the value of a "query" field in the JSON object within the request payload. For example: -```json -{"query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar'"} -``` +Submits a SQL-based query in the JSON request body. Returns a JSON object with the query results and optional metadata for the results. You can also use this endpoint to query [metadata tables](../querying/sql-metadata-tables.md). -### Request body - -|Property|Description|Default| -|--------|----|-----------| -|`query`|SQL query string.| none (required)| -|`resultFormat`|Format of query results. See [Responses](#responses) for details.|`"object"`| -|`header`|Whether or not to include a header row for the query result. See [Responses](#responses) for details.|`false`| -|`typesHeader`|Whether or not to include type information in the header. Can only be set when `header` is also `true`. See [Responses](#responses) for details.|`false`| -|`sqlTypesHeader`|Whether or not to include SQL type information in the header. Can only be set when `header` is also `true`. See [Responses](#responses) for details.|`false`| -|`context`|JSON object containing [SQL query context parameters](../querying/sql-query-context.md).|`{}` (empty)| -|`parameters`|List of query parameters for parameterized queries. Each parameter in the list should be a JSON object like `{"type": "VARCHAR", "value": "foo"}`. The type should be a SQL type; see [Data types](../querying/sql-data-types.md) for a list of supported SQL types.|`[]` (empty)| - -You can use _curl_ to send SQL queries from the command-line: - -```bash -$ cat query.json -{"query":"SELECT COUNT(*) AS TheCount FROM data_source"} - -$ curl -XPOST -H'Content-Type: application/json' http://ROUTER:8888/druid/v2/sql/ -d @query.json -[{"TheCount":24433}] -``` +Each query can be identified with the SQL context parameter `sqlQueryId`. The `sqlQueryId` can be set manually in the request payload with the `sqlQueryId` context parameter. If not set, Druid automatically generates a `sqlQueryId` and returns it in the response header. Note that the `sqlQueryId` is required to use the [cancel a query](#cancel-a-query) endpoint. Review Comment: ```suggestion Each query has an associated SQL query ID. You can set this ID manually using the SQL context parameter `sqlQueryId`. If not set, Druid automatically generates `sqlQueryId` and returns it in the response header for `X-Druid-SQL-Query-Id`. Note that you need the `sqlQueryId` to [cancel a query](#cancel-a-query) endpoint. ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
