vtlim commented on code in PR #14711: URL: https://github.com/apache/druid/pull/14711#discussion_r1281011053
########## docs/api-reference/sql-api.md: ########## @@ -23,167 +23,287 @@ 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 place holder 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'"} -``` +Submit a SQL-based query in the JSON request body. Returns a JSON object with the database results and a set of header metadata associated with the query. -### 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}] -``` +This endpoint also supports querying metadata by using [metadata tables](../querying/sql-metadata-tables.md). + +#### URL + +<code class="postAPI">POST</code> <code>/druid/v2/sql</code> + +#### Request body + +* `query`: SQL query string. +* `resultFormat`: Format of query results. + * `object`: Returns a JSON array of JSON objects with the HTTP header `Content-Type: application/json`. + * `array`: Returns a JSON array of JSON arrays with the HTTP header `Content-Type: application/json`. + * `objectLines`: Returns newline-delimited JSON objects with a trailing blank line. Sent with the HTTP header `Content-Type: text/plain`. + * `arrayLines`: Returns newline-delimited JSON arrays with a trailing blank line. Sent with the HTTP header `Content-Type: text/plain`. + * `csv`: Returns a comma-separated values with one row per line and a trailing blank line. Sent with the HTTP header `Content-Type: text/csv`. +* `header`: Adds a header row with information on column names for the query result when set to `true`. You can optionally include `typesHeader` and `sqlTypesHeader`. + + Complex types, like sketches, will be reported as `COMPLEX<typeName>` if a particular complex type name is known for that field, or as `COMPLEX` if the particular type name is unknown or mixed. + + If working with an older version of Druid, set `header` to `true` to verify compatibility. Druid returns the HTTP header `X-Druid-SQL-Header-Included: yes` when the client connects to an older Druid version with support for the `typesHeader` and `sqlTypesHeader` parameters. Additionally, Druid returns a `X-Druid-SQL-Query-Id` HTTP header with the value of `sqlQueryId` from the [query context parameters](../querying/sql-query-context.md) if specified, else Druid will generate a SQL query ID. Review Comment: ```suggestion Older versions of Druid that support the `typesHeader` and `sqlTypesHeader` parameters return the HTTP header `X-Druid-SQL-Header-Included: yes` when you set `header` to `true`. Druid returns the HTTP response header for compatibility, regardless of whether `typesHeader` and `sqlTypesHeader` are set. ``` Suggested rewording to retain the original message -- 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]
