[GitHub] [druid] jihoonson commented on a change in pull request #11708: docs: delete / cancel query

[GitBox <gi...@apache.org>]

jihoonson commented on a change in pull request #11708:
URL: https://github.com/apache/druid/pull/11708#discussion_r708622787



##########
File path: docs/querying/sql.md
##########
@@ -956,6 +955,30 @@ trailer they all include: one blank line at the end of the result set. If you de
 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. When you cancel a query canceled, Druid marks its `SqlLifecycle` canceled immediately. After that, any operations in `SqlLifecycle` become non-operational to avoid unnecessary execution of expensive operations.

Review comment:
       This seems a bit of leaking too much information since `SqlLifecycle` doesn't have to be exposed to end users. How about
    
   ```suggestion
   You can use the HTTP `DELETE` method to cancel a SQL query. The query cancellation is done in a best-effort manner. When you cancel a query, Druid marks the query canceled immediately and aborts the query execution as soon as it is possible. Since the query cancellation is best-effort, your query may be running for a while even after you cancel it.
   ```

##########
File path: docs/querying/sql.md
##########
@@ -956,6 +955,30 @@ trailer they all include: one blank line at the end of the result set. If you de
 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. When you cancel a query canceled, Druid marks its `SqlLifecycle` canceled immediately. After that, any operations in `SqlLifecycle` become non-operational to avoid unnecessary execution of expensive operations.
+
+HTTP DELETE method uses the following syntax:
+```
+DELETE https://BROKER:8082/druid/v2/sql/{sqlQueryId}
+```
+
+The DELETE method requires the `sqlQueryId`, therefore to predict the query id you must set it in the query context.
+
+For example if you issue the following query:
+```bash
+curl --request POST 'https://BROKER:8082/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 as follows:
+```bash
+curl --request DELETE 'https://BROKER:8082/druid/v2/sql/myQuery01' \
+```
+
+Druid returns an HTTP 202 response for successful deletion requests. If the the query id is incorrect or if the query completes before your cancellation request, Druid returns an HTTP 404 response. 

Review comment:
       The cancellation request requires the read permission on all resources (currently datasource and view) in the sql query. It returns 404 as well when authorization fails.

##########
File path: docs/querying/sql.md
##########
@@ -956,6 +955,30 @@ trailer they all include: one blank line at the end of the result set. If you de
 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. When you cancel a query canceled, Druid marks its `SqlLifecycle` canceled immediately. After that, any operations in `SqlLifecycle` become non-operational to avoid unnecessary execution of expensive operations.
+
+HTTP DELETE method uses the following syntax:
+```
+DELETE https://BROKER:8082/druid/v2/sql/{sqlQueryId}
+```
+
+The DELETE method requires the `sqlQueryId`, therefore to predict the query id you must set it in the query context.

Review comment:
       Queries are allowed to have the same sqlQueryId even when they are different. It would be nice to mention that all queries will be cancelled if you have multiple sql queries running with the same sqlQueryId.

##########
File path: docs/querying/sql.md
##########
@@ -956,6 +955,30 @@ trailer they all include: one blank line at the end of the result set. If you de
 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. When you cancel a query canceled, Druid marks its `SqlLifecycle` canceled immediately. After that, any operations in `SqlLifecycle` become non-operational to avoid unnecessary execution of expensive operations.
+
+HTTP DELETE method uses the following syntax:
+```
+DELETE https://BROKER:8082/druid/v2/sql/{sqlQueryId}

Review comment:
       I'm wondering whether we should promote using router instead of broker since the router is now sort of mandatory to use the web console. Or, should we mention that you can use either router or broker address here?




-- 
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: commits-unsubscribe@druid.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@druid.apache.org
For additional commands, e-mail: commits-help@druid.apache.org