vtlim commented on code in PR #14492:
URL: https://github.com/apache/druid/pull/14492#discussion_r1245925124
##########
docs/api-reference/tasks-api.md:
##########
@@ -25,77 +25,1448 @@ sidebar_label: Tasks
This document describes the API endpoints for task retrieval, submission, and
deletion for Apache Druid.
-## Tasks
-
Note that all _interval_ URL parameters are ISO 8601 strings delimited by a
`_` instead of a `/`
as in `2016-06-27_2016-06-28`.
-`GET /druid/indexer/v1/tasks`
+## Task information and retrieval
+
+### Get an array of tasks
+
+#### URL
+<code class="getAPI">GET</code> `/druid/indexer/v1/tasks`
+
+This endpoint retrieves an array of all task objects currently running or
executed in the current Druid cluster. It provides information about each task
such as its task id, task status, associated data source, and other metadata.
It supports a set of optional query parameters to filter results.
+
+#### Query parameters
+|Parameter|Type|Description|
+|---|---|---|
+|`state`|String|Filter list of tasks by task state, valid options are
`running`, `complete`, `waiting`, and `pending`.|
+| `datasource`|String| Return tasks filtered by Druid datasource.|
+| `createdTimeInterval`|String (ISO-8601)| Return tasks created within the
specified interval. |
+| `max`|Integer|Maximum number of `"complete"` tasks to return. Only applies
when `state` is set to `"complete"`.|
+| `type`|String|Filter tasks by task type. See [task
documentation](../ingestion/tasks.md) for more details.|
+
+#### Responses
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--200 SUCCESS-->
+<br/>
+*Successfully retrieved list of tasks*
+<!--400 BAD REQUEST-->
+<br/>
+*Invalid `state` query parameter value*
+<!--500 SERVER ERROR-->
+<br/>
+*Invalid query parameter*
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+#### Sample request
+
+The following example shows how to retrieve a list of tasks filtered with the
following query parameters:
+* State: `complete`
+* Datasource: `wikipedia_api`
+* Time interval: between `2015-09-12` and `2015-09-13`
+* Max entries returned: `10`
+* Task type: `query_worker`
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--cURL-->
+```shell
+curl
"{domain}/druid/indexer/v1/tasks/?state=complete&datasource=wikipedia_api&createdTimeInterval=2015-09-12T00%3A00%3A00Z%2F2015-09-13T23%3A59%3A59Z&max=10&type=query_worker"
+```
+<!--HTTP-->
+```HTTP
+GET
/druid/indexer/v1/tasks/?state=complete&datasource=wikipedia_api&createdTimeInterval=2015-09-12T00%3A00%3A00Z%2F2015-09-13T23%3A59%3A59Z&max=10&type=query_worker
HTTP/1.1
+Host: {domain}
+```
+
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+#### Sample response
+
+<details>
+ <summary>Click to show sample response</summary>
+
+ ```json
+ [
+ {
+ "id": "query-223549f8-b993-4483-b028-1b0d54713cad-worker0_0",
+ "groupId": "query-223549f8-b993-4483-b028-1b0d54713cad",
+ "type": "query_worker",
+ "createdTime": "2023-06-22T22:11:37.012Z",
+ "queueInsertionTime": "1970-01-01T00:00:00.000Z",
+ "statusCode": "SUCCESS",
+ "status": "SUCCESS",
+ "runnerStatusCode": "NONE",
+ "duration": 17897,
+ "location": {
+ "host": "localhost",
+ "port": 8101,
+ "tlsPort": -1
+ },
+ "dataSource": "wikipedia_api",
+ "errorMsg": null
+ },
+ {
+ "id": "query-fa82fa40-4c8c-4777-b832-cabbee5f519f-worker0_0",
+ "groupId": "query-fa82fa40-4c8c-4777-b832-cabbee5f519f",
+ "type": "query_worker",
+ "createdTime": "2023-06-20T22:51:21.302Z",
+ "queueInsertionTime": "1970-01-01T00:00:00.000Z",
+ "statusCode": "SUCCESS",
+ "status": "SUCCESS",
+ "runnerStatusCode": "NONE",
+ "duration": 16911,
+ "location": {
+ "host": "localhost",
+ "port": 8101,
+ "tlsPort": -1
+ },
+ "dataSource": "wikipedia_api",
+ "errorMsg": null
+ },
+ {
+ "id": "query-5419da7a-b270-492f-90e6-920ecfba766a-worker0_0",
+ "groupId": "query-5419da7a-b270-492f-90e6-920ecfba766a",
+ "type": "query_worker",
+ "createdTime": "2023-06-20T22:45:53.909Z",
+ "queueInsertionTime": "1970-01-01T00:00:00.000Z",
+ "statusCode": "SUCCESS",
+ "status": "SUCCESS",
+ "runnerStatusCode": "NONE",
+ "duration": 17030,
+ "location": {
+ "host": "localhost",
+ "port": 8101,
+ "tlsPort": -1
+ },
+ "dataSource": "wikipedia_api",
+ "errorMsg": null
+ }
+ ]
+ ```
+
+</details>
+
+### Get an array of complete tasks
+
+#### URL
+<code class="getAPI">GET</code> `/druid/indexer/v1/completeTasks`
+
+This endpoint retrieves an array of completed task objects in the current
Druid cluster. This is functionally equivalent to
`/druid/indexer/v1/tasks?state=complete`. It supports a set of optional query
parameters to filter results.
+
+#### Query parameters
+|Parameter|Type|Description|
+|---|---|---|
+| `datasource`|String| Return tasks filtered by Druid datasource.|
+| `createdTimeInterval`|String (ISO-8601)| Return tasks created within the
specified interval. |
+| `max`|Integer|Maximum number of `"complete"` tasks to return. Only applies
when `state` is set to `"complete"`.|
+| `type`|String|Filter tasks by task type. See [task
documentation](../ingestion/tasks.md) for more details.|
+
+#### Responses
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--200 SUCCESS-->
+<br/>
+*Successfully retrieved list of complete tasks*
+<!--404 NOT FOUND-->
+<br/>
+*Request sent to incorrect service*
+
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+#### Sample request
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--cURL-->
+```shell
+curl "{domain}/druid/indexer/v1/completeTasks"
+```
+<!--HTTP-->
+```HTTP
+GET /druid/indexer/v1/completeTasks HTTP/1.1
+Host: {domain}
+```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+#### Sample response
+
+<details>
+ <summary>Click to show sample response</summary>
+
+ ```json
+ [
+ {
+ "id": "query-223549f8-b993-4483-b028-1b0d54713cad-worker0_0",
+ "groupId": "query-223549f8-b993-4483-b028-1b0d54713cad",
+ "type": "query_worker",
+ "createdTime": "2023-06-22T22:11:37.012Z",
+ "queueInsertionTime": "1970-01-01T00:00:00.000Z",
+ "statusCode": "SUCCESS",
+ "status": "SUCCESS",
+ "runnerStatusCode": "NONE",
+ "duration": 17897,
+ "location": {
+ "host": "localhost",
+ "port": 8101,
+ "tlsPort": -1
+ },
+ "dataSource": "wikipedia_api",
+ "errorMsg": null
+ },
+ {
+ "id": "query-223549f8-b993-4483-b028-1b0d54713cad",
+ "groupId": "query-223549f8-b993-4483-b028-1b0d54713cad",
+ "type": "query_controller",
+ "createdTime": "2023-06-22T22:11:28.367Z",
+ "queueInsertionTime": "1970-01-01T00:00:00.000Z",
+ "statusCode": "SUCCESS",
+ "status": "SUCCESS",
+ "runnerStatusCode": "NONE",
+ "duration": 30317,
+ "location": {
+ "host": "localhost",
+ "port": 8100,
+ "tlsPort": -1
+ },
+ "dataSource": "wikipedia_api",
+ "errorMsg": null
+ }
+ ]
+ ```
+
+</details>
+
+### Get an array of running tasks
+
+#### URL
+<code class="getAPI">GET</code> `/druid/indexer/v1/runningTasks`
+
+This endpoint retrieves an array of running task objects in the current Druid
cluster. It is functionally equivalent to
`/druid/indexer/v1/tasks?state=running`. It supports a set of optional query
parameters to filter results.
+
+#### Query parameters
+|Parameter|Type|Description|
+|---|---|---|
+| `datasource`|String| Return tasks filtered by Druid datasource.|
+| `createdTimeInterval`|String (ISO-8601)| Return tasks created within the
specified interval. |
+| `max`|Integer|Maximum number of `"complete"` tasks to return. Only applies
when `state` is set to `"complete"`.|
+| `type`|String|Filter tasks by task type. See [task
documentation](../ingestion/tasks.md) for more details.|
+
+#### Responses
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--200 SUCCESS-->
+<br/>
+*Successfully retrieved list of running tasks*
+
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+#### Sample request
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--cURL-->
+```shell
+curl "{domain}/druid/indexer/v1/runningTasks"
+```
+<!--HTTP-->
+```HTTP
+GET /druid/indexer/v1/runningTasks HTTP/1.1
+Host: {domain}
+```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+#### Sample response
+
+<details>
+ <summary>Click to show sample response</summary>
+
+ ```json
+ [
+ {
+ "id": "query-32663269-ead9-405a-8eb6-0817a952ef47",
+ "groupId": "query-32663269-ead9-405a-8eb6-0817a952ef47",
+ "type": "query_controller",
+ "createdTime": "2023-06-22T22:54:43.170Z",
+ "queueInsertionTime": "2023-06-22T22:54:43.170Z",
+ "statusCode": "RUNNING",
+ "status": "RUNNING",
+ "runnerStatusCode": "RUNNING",
+ "duration": -1,
+ "location": {
+ "host": "localhost",
+ "port": 8100,
+ "tlsPort": -1
+ },
+ "dataSource": "wikipedia_api",
+ "errorMsg": null
+ }
+ ]
+ ```
+
+</details>
+
+### Get an array of waiting tasks
+
+#### URL
+<code class="getAPI">GET</code> `/druid/indexer/v1/waitingTasks`
+
+This endpoint retrieves an array of waiting task objects in the current Druid
cluster. It is functionally equivalent to
`/druid/indexer/v1/tasks?state=waiting`. It supports a set of optional query
parameters to filter results.
-Retrieve list of tasks. Accepts query string parameters `state`, `datasource`,
`createdTimeInterval`, `max`, and `type`.
+#### Query parameters
+|Parameter|Type|Description|
+|---|---|---|
+| `datasource`|String| Return tasks filtered by Druid datasource.|
+| `createdTimeInterval`|String (ISO-8601)| Return tasks created within the
specified interval. |
+| `max`|Integer|Maximum number of `"complete"` tasks to return. Only applies
when `state` is set to `"complete"`.|
+| `type`|String|Filter tasks by task type. See [task
documentation](../ingestion/tasks.md) for more details.|
-|Query Parameter |Description |
-|---|---|
-|`state`|filter list of tasks by task state, valid options are `running`,
`complete`, `waiting`, and `pending`.|
-| `datasource`| return tasks filtered by Druid datasource.|
-| `createdTimeInterval`| return tasks created within the specified interval. |
-| `max`| maximum number of `"complete"` tasks to return. Only applies when
`state` is set to `"complete"`.|
-| `type`| filter tasks by task type. See [task
documentation](../ingestion/tasks.md) for more details.|
+#### Responses
+<!--DOCUSAURUS_CODE_TABS-->
-`GET /druid/indexer/v1/completeTasks`
+<!--200 SUCCESS-->
+<br/>
+*Successfully retrieved list of waiting tasks*
-Retrieve list of complete tasks. Equivalent to
`/druid/indexer/v1/tasks?state=complete`.
+<!--END_DOCUSAURUS_CODE_TABS-->
-`GET /druid/indexer/v1/runningTasks`
+#### Sample request
-Retrieve list of running tasks. Equivalent to
`/druid/indexer/v1/tasks?state=running`.
+<!--DOCUSAURUS_CODE_TABS-->
-`GET /druid/indexer/v1/waitingTasks`
+<!--cURL-->
+```shell
+curl "{domain}/druid/indexer/v1/waitingTasks"
+```
+<!--HTTP-->
+```HTTP
+GET /druid/indexer/v1/waitingTasks HTTP/1.1
+Host: {domain}
+```
+<!--END_DOCUSAURUS_CODE_TABS-->
-Retrieve list of waiting tasks. Equivalent to
`/druid/indexer/v1/tasks?state=waiting`.
+#### Sample response
-`GET /druid/indexer/v1/pendingTasks`
+<details>
+ <summary>Click to show sample response</summary>
+
+ ```json
+ [
+ {
+ "id":
"index_parallel_wikipedia_auto_biahcbmf_2023-06-26T21:08:05.216Z",
+ "groupId":
"index_parallel_wikipedia_auto_biahcbmf_2023-06-26T21:08:05.216Z",
+ "type": "index_parallel",
+ "createdTime": "2023-06-26T21:08:05.217Z",
+ "queueInsertionTime": "1970-01-01T00:00:00.000Z",
+ "statusCode": "RUNNING",
+ "status": "RUNNING",
+ "runnerStatusCode": "WAITING",
+ "duration": -1,
+ "location": {
+ "host": null,
+ "port": -1,
+ "tlsPort": -1
+ },
+ "dataSource": "wikipedia_auto",
+ "errorMsg": null
+ },
+ {
+ "id":
"index_parallel_wikipedia_auto_afggfiec_2023-06-26T21:08:05.546Z",
+ "groupId":
"index_parallel_wikipedia_auto_afggfiec_2023-06-26T21:08:05.546Z",
+ "type": "index_parallel",
+ "createdTime": "2023-06-26T21:08:05.548Z",
+ "queueInsertionTime": "1970-01-01T00:00:00.000Z",
+ "statusCode": "RUNNING",
+ "status": "RUNNING",
+ "runnerStatusCode": "WAITING",
+ "duration": -1,
+ "location": {
+ "host": null,
+ "port": -1,
+ "tlsPort": -1
+ },
+ "dataSource": "wikipedia_auto",
+ "errorMsg": null
+ },
+ {
+ "id":
"index_parallel_wikipedia_auto_jmmddihf_2023-06-26T21:08:06.644Z",
+ "groupId":
"index_parallel_wikipedia_auto_jmmddihf_2023-06-26T21:08:06.644Z",
+ "type": "index_parallel",
+ "createdTime": "2023-06-26T21:08:06.671Z",
+ "queueInsertionTime": "1970-01-01T00:00:00.000Z",
+ "statusCode": "RUNNING",
+ "status": "RUNNING",
+ "runnerStatusCode": "WAITING",
+ "duration": -1,
+ "location": {
+ "host": null,
+ "port": -1,
+ "tlsPort": -1
+ },
+ "dataSource": "wikipedia_auto",
+ "errorMsg": null
+ }
+ ]
+ ```
-Retrieve list of pending tasks. Equivalent to
`/druid/indexer/v1/tasks?state=pending`.
+</details>
-`GET /druid/indexer/v1/task/{taskId}`
+### Get an array of pending tasks
-Retrieve the 'payload' of a task.
+#### URL
-`GET /druid/indexer/v1/task/{taskId}/status`
+<code class="getAPI">GET</code> `/druid/indexer/v1/pendingTasks`
-Retrieve the status of a task.
+This endpoint retrieves an array of pending task objects in the current Druid
cluster. It is functionally equivalent to
`/druid/indexer/v1/tasks?state=pending`. It supports a set of optional query
parameters to filter results.
-`GET /druid/indexer/v1/task/{taskId}/segments`
+#### Query parameters
+|Parameter|Type|Description|
+|---|---|---|
+| `datasource`|String| Return tasks filtered by Druid datasource.|
+| `createdTimeInterval`|String (ISO-8601)| Return tasks created within the
specified interval. |
+| `max`|Integer|Maximum number of `"complete"` tasks to return. Only applies
when `state` is set to `"complete"`.|
+| `type`|String|Filter tasks by task type. See [task
documentation](../ingestion/tasks.md) for more details.|
+
+#### Responses
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--200 SUCCESS-->
+<br/>
+*Successfully retrieved list of pending tasks*
+
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+#### Sample request
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--cURL-->
+```shell
+curl "{domain}/druid/indexer/v1/pendingTasks"
+```
+<!--HTTP-->
+```HTTP
+GET /druid/indexer/v1/pendingTasks HTTP/1.1
+Host: {domain}
+```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+#### Sample response
+
+<details>
+ <summary>Click to show sample response</summary>
+
+ ```json
+ [
+ {
+ "id": "query-7b37c315-50a0-4b68-aaa8-b1ef1f060e67",
+ "groupId": "query-7b37c315-50a0-4b68-aaa8-b1ef1f060e67",
+ "type": "query_controller",
+ "createdTime": "2023-06-23T19:53:06.037Z",
+ "queueInsertionTime": "2023-06-23T19:53:06.037Z",
+ "statusCode": "RUNNING",
+ "status": "RUNNING",
+ "runnerStatusCode": "PENDING",
+ "duration": -1,
+ "location": {
+ "host": null,
+ "port": -1,
+ "tlsPort": -1
+ },
+ "dataSource": "wikipedia_api",
+ "errorMsg": null
+ },
+ {
+ "id": "query-544f0c41-f81d-4504-b98b-f9ab8b36ef36",
+ "groupId": "query-544f0c41-f81d-4504-b98b-f9ab8b36ef36",
+ "type": "query_controller",
+ "createdTime": "2023-06-23T19:53:06.616Z",
+ "queueInsertionTime": "2023-06-23T19:53:06.616Z",
+ "statusCode": "RUNNING",
+ "status": "RUNNING",
+ "runnerStatusCode": "PENDING",
+ "duration": -1,
+ "location": {
+ "host": null,
+ "port": -1,
+ "tlsPort": -1
+ },
+ "dataSource": "wikipedia_api",
+ "errorMsg": null
+ }
+ ]
+ ```
+
+</details>
+
+### Get task payload
+
+#### URL
+<code class="getAPI">GET</code> `/druid/indexer/v1/task/{taskId}`
+
+Retrieves the payload of a task given the task id. It returns a JSON object
with the task id and payload which includes task configuration details and
relevant specifications associated with the execution of the task.
Review Comment:
Also stay consistent on whether the description starts with "Retrieves" or
"Retrieve"
--
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]
