docs: delete / cancel query (#11708)
* draft delete query
* Update docs/querying/sql.md
Co-authored-by: Jihoon Son <jihoonson@apache.org>
* Update docs/querying/sql.md
Co-authored-by: Victoria Lim <vtlim@users.noreply.github.com>
* Update docs/querying/sql.md
Co-authored-by: Victoria Lim <vtlim@users.noreply.github.com>
* address comments
* Update docs/querying/sql.md
Co-authored-by: Jihoon Son <jihoonson@apache.org>
* Update docs/querying/sql.md
Co-authored-by: Jihoon Son <jihoonson@apache.org>
* Update sql.md
fix port for router
* Update sql.md
remove authorization until it is 403
* Update sql.md
add 403 message
Co-authored-by: Jihoon Son <jihoonson@apache.org>
Co-authored-by: Victoria Lim <vtlim@users.noreply.github.com>
diff --git a/docs/querying/sql.md b/docs/querying/sql.md
index f9c765b..18d9e6e 100644
--- a/docs/querying/sql.md
+++ b/docs/querying/sql.md
@@ -849,7 +849,6 @@
- [Inline datasources](datasource.md#inline).
- [Spatial filters](../development/geo.md).
-- [Query cancellation](querying.md#query-cancellation).
- [Multi-value dimensions](#multi-value-strings) are only partially implemented in Druid SQL. There are known
inconsistencies between their behavior in SQL queries and in native queries due to how they are currently treated by
the SQL planner.
@@ -860,8 +859,15 @@
### HTTP POST
-You can make Druid SQL queries using HTTP via POST to the endpoint `/druid/v2/sql/`. The request should
-be a JSON object with a "query" field, like `{"query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar'"}`.
+To use the SQL API to make Druid SQL queries, POST your query to the following endpoint on either the Router or Broker:
+```
+POST https://ROUTER:8888/druid/v2/sql/`.
+```
+
+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'"}
+```
##### Request
@@ -879,7 +885,7 @@
$ cat query.json
{"query":"SELECT COUNT(*) AS TheCount FROM data_source"}
-$ curl -XPOST -H'Content-Type: application/json' http://BROKER:8082/druid/v2/sql/ -d @query.json
+$ curl -XPOST -H'Content-Type: application/json' http://ROUTER:8888/druid/v2/sql/ -d @query.json
[{"TheCount":24433}]
```
@@ -956,6 +962,38 @@
through a JSON parsing error or through a missing trailing newline, you should assume the response was not fully
delivered due to an error.
+### HTTP DELETE
+You can use the HTTP `DELETE` method to cancel a SQL query on either the Router or the Broker. When you cancel a query, Druid handles the cancellation in a best-effort manner. It marks the query canceled immediately and aborts the query execution as soon as possible. However, your query may run for a short time after your cancellation request.
+
+Druid SQL's HTTP DELETE method uses the following syntax:
+```
+DELETE https://ROUTER:8888/druid/v2/sql/{sqlQueryId}
+```
+
+The DELETE method requires the `sqlQueryId` path parameter. To predict the query id you must set it in the query context. Druid does not enforce unique `sqlQueryId` in the query context. If you issue a cancel request for a `sqlQueryId` active in more than one query context, Druid cancels all requests that use the query id.
+
+For example if you issue the following query:
+```bash
+curl --request POST 'https://ROUTER:8888/druid/v2/sql' \
+--header 'Content-Type: application/json' \
+--data-raw '{"query" : "SELECT sleep(CASE WHEN sum_added > 0 THEN 1 ELSE 0 END) FROM wikiticker WHERE sum_added > 0 LIMIT 15",
+"context" : {"sqlQueryId" : "myQuery01"}}'
+```
+You can cancel the query using the query id `myQuery01` as follows:
+```bash
+curl --request DELETE 'https://ROUTER:8888/druid/v2/sql/myQuery01' \
+```
+
+Cancellation requests require READ permission on all resources used in the sql query.
+
+Druid returns an HTTP 202 response for successful deletion requests.
+
+Druid returns an HTTP 404 response in the following cases:
+ - `sqlQueryId` is incorrect.
+ - The query completes before your cancellation request is processed.
+
+Druid returns an HTTP 403 response for authorization failure.
+
### JDBC
You can make Druid SQL queries using the [Avatica JDBC driver](https://calcite.apache.org/avatica/downloads/). We recommend using Avatica JDBC driver version 1.17.0 or later. Note that as of the time of this writing, Avatica 1.17.0, the latest version, does not support passing connection string parameters from the URL to Druid, so you must pass them using a `Properties` object. Once you've downloaded the Avatica client jar, add it to your classpath and use the connect string `jdbc:avatica:remote:url=http://BROKER:8082/druid/v2/sql/avatica/`.
