cryptoe opened a new pull request, #14416: URL: https://github.com/apache/druid/pull/14416
<!-- Thanks for trying to help us make Apache Druid be the best it can be! Please fill out as much of the following information as is possible (where relevant, and remove it when irrelevant) to help make the intention and scope of this PR clear in order to ease review. --> <!-- Please read the doc for contribution (https://github.com/apache/druid/blob/master/CONTRIBUTING.md) before making this PR. Also, once you open a PR, please _avoid using force pushes and rebasing_ since these make it difficult for reviewers to see what you've changed in response to their reviews. See [the 'If your pull request shows conflicts with master' section](https://github.com/apache/druid/blob/master/CONTRIBUTING.md#if-your-pull-request-shows-conflicts-with-master) for more details. --> The current SQL endpoint is more suited toward hot queries where the client blocks for the results. The current task endpoint is more of a fire-and-forget API, primarily meant for ingestion. This PR aims to expose a new API called "@Path("/druid/v2/sql/statements/")" which takes the same payload as the current "/druid/v2/sql" endpoint and allows users to fetch results in an async manner. The statement execution API runs a single SQL statement which can be: SELECT DDL CREATE [TEMPORARY|EXTERNAL] TABLE AS INSERT ### POST SQL statement `POST /sql/statements` Executes a SQL statement. * Request: The post payload is in the same format as https://druid.apache.org/docs/latest/querying/sql.html#http-post so that users can easily switch to the new async apis. Two additional context field: ``` mode: Determines how the query results are fetched. It will have 3 values [SYNC, ASYNC, AUTO] . For the MVP mode=ASYNC is only supported. execTimeout: The maximum amount of time that the query can execute. Handy to prevent “runaway queries.” Must be lower than any system-configured value. This is distinct from the results expiration timeout. Optional.(not supported for initial version) ``` * Response ``` #http 200 { "state":"RUNNING", "queryID":"queryIDXX", "createdAt":"2023-03-07T12:58:17Z", "schema": [ { "name": "col1", "type": "varchar" }, { "name": "col2", "type": "varchar" } ] } ``` ``` #http 200 { "state": "FINISHED", "createdAt": "2023-03-07T12:58:17Z", "queryID": "queryIDXX", "durationInMS": 20, "schema": [ { "name": "col1", "type": "varchar" }, { "name": "col2", "type": "varchar" } ], "result": { "totalRows": 12412, "totalSize": 12000, "format":"json", "header":true, "sampleRecords": [] } } ``` ### Query execution failures This sections is exactly similar as https://druid.apache.org/docs/latest/querying/querying.html#query-execution-failures If a query fails, Druid returns a response with an HTTP response code and a JSON object with the following structure: ``` { "error" : "Query timeout", "errorMessage" : "Timeout waiting for task.", "errorClass" : "java.util.concurrent.TimeoutException", "host" : "druid1.example.com:8083" } ``` ### Status `GET /sql/statements/{id}` Returns the same response as the post API. ### Results `GET /sql/statements/{id}/results?offset=x&numRows=y&size=s&timeout=z` Returns a page of results if they are read Parameter names are preliminary: the goal here is to list them, not finalize names: ``` id Query Id. offset. Row offset of the first row to fetch. numRows: number of rows to fetch size: Size limit of the results, in bytes. (Optional: size limit in rows. The smallest value wins.) timeout: The timeout, in MS, to wait for results. The request returns when the timeout is hit, regardless of size. The results can be zero rows. ``` ### Close Query `DELETE /sql/statements/{id}` Cancels a running/accepted query. <!-- Replace XXXX with the id of the issue fixed in this PR. Remove this section if there is no corresponding issue. Don't reference the issue in the title of this pull-request. --> <!-- If you are a committer, follow the PR action item checklist for committers: https://github.com/apache/druid/blob/master/dev/committer-instructions.md#pr-and-issue-action-item-checklist-for-committers. --> ### Description <!-- Describe the goal of this PR, what problem are you fixing. If there is a corresponding issue (referenced above), it's not necessary to repeat the description here, however, you may choose to keep one summary sentence. --> <!-- Describe your patch: what did you change in code? How did you fix the problem? --> <!-- If there are several relatively logically separate changes in this PR, create a mini-section for each of them. For example: --> ### TODO * Add more java docs * UT's <!-- Check the items by putting "x" in the brackets for the done things. Not all of these items apply to every PR. Remove the items which are not done or not relevant to the PR. None of the items from the checklist below are strictly necessary, but it would be very helpful if you at least self-review the PR. --> This PR has: - [ ] been self-reviewed. - [ ] using the [concurrency checklist](https://github.com/apache/druid/blob/master/dev/code-review/concurrency.md) (Remove this item if the PR doesn't have any relation to concurrency.) - [ ] added documentation for new or modified features or behaviors. - [ ] a release note entry in the PR description. - [ ] added Javadocs for most classes and all non-trivial methods. Linked related entities via Javadoc links. - [ ] added or updated version, license, or notice information in [licenses.yaml](https://github.com/apache/druid/blob/master/dev/license.md) - [ ] added comments explaining the "why" and the intent of the code wherever would not be obvious for an unfamiliar reader. - [ ] added unit tests or modified existing tests to cover new code paths, ensuring the threshold for [code coverage](https://github.com/apache/druid/blob/master/dev/code-review/code-coverage.md) is met. - [ ] added integration tests. - [ ] been tested in a test Druid cluster. -- 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]
