From a4cf4ca585920c2001ce33beff2b4a84e3a2d243 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Tue, 2 Oct 2018 08:37:45 -0700 Subject: [PATCH] [DOCS] Clarifies examples in reindex and task APIs (#33143) --- docs/reference/cluster/tasks.asciidoc | 36 +++++++++----------- docs/reference/docs/delete-by-query.asciidoc | 20 +++++------ docs/reference/docs/reindex.asciidoc | 34 ++++++++++-------- docs/reference/docs/update-by-query.asciidoc | 22 ++++++------ 4 files changed, 54 insertions(+), 58 deletions(-) diff --git a/docs/reference/cluster/tasks.asciidoc b/docs/reference/cluster/tasks.asciidoc index d6dfa71b76b..c84f4c43ae8 100644 --- a/docs/reference/cluster/tasks.asciidoc +++ b/docs/reference/cluster/tasks.asciidoc @@ -16,6 +16,7 @@ GET _tasks?nodes=nodeId1,nodeId2 <2> GET _tasks?nodes=nodeId1,nodeId2&actions=cluster:* <3> -------------------------------------------------- // CONSOLE +// TEST[skip:No tasks to retrieve] <1> Retrieves all tasks currently running on all nodes in the cluster. <2> Retrieves all tasks running on nodes `nodeId1` and `nodeId2`. See <> for more info about how to select individual nodes. @@ -57,31 +58,29 @@ The result will look similar to the following: } } -------------------------------------------------- -// NOTCONSOLE -// We can't test tasks output +// TESTRESPONSE -It is also possible to retrieve information for a particular task: +It is also possible to retrieve information for a particular task. The following +example retrieves information about task `oTUltX4IQMOUUVeiohTt8A:124`: [source,js] -------------------------------------------------- -GET _tasks/task_id <1> +GET _tasks/oTUltX4IQMOUUVeiohTt8A:124 -------------------------------------------------- // CONSOLE -// TEST[s/task_id/node_id:1/] // TEST[catch:missing] -<1> This will return a 404 if the task isn't found. +If the task isn't found, the API returns a 404. -Or to retrieve all children of a particular task: +To retrieve all children of a particular task: [source,js] -------------------------------------------------- -GET _tasks?parent_task_id=parent_task_id <1> +GET _tasks?parent_task_id=oTUltX4IQMOUUVeiohTt8A:123 -------------------------------------------------- // CONSOLE -// TEST[s/=parent_task_id/=node_id:1/] -<1> This won't return a 404 if the parent isn't found. +If the parent isn't found, the API does not return a 404. You can also use the `detailed` request parameter to get more information about the running tasks. This is useful for telling one task from another but is more @@ -93,8 +92,9 @@ request parameter: GET _tasks?actions=*search&detailed -------------------------------------------------- // CONSOLE +// TEST[skip:No tasks to retrieve] -might look like: +The results might look like: [source,js] -------------------------------------------------- @@ -121,8 +121,7 @@ might look like: } } -------------------------------------------------- -// NOTCONSOLE -// We can't test tasks output +// TESTRESPONSE The new `description` field contains human readable text that identifies the particular request that the task is performing such as identifying the search @@ -167,14 +166,14 @@ GET _cat/tasks?detailed [[task-cancellation]] === Task Cancellation -If a long-running task supports cancellation, it can be cancelled by the following command: +If a long-running task supports cancellation, it can be cancelled with the cancel +tasks API. The following example cancels task `oTUltX4IQMOUUVeiohTt8A:12345`: [source,js] -------------------------------------------------- -POST _tasks/node_id:task_id/_cancel +POST _tasks/oTUltX4IQMOUUVeiohTt8A:12345/_cancel -------------------------------------------------- // CONSOLE -// TEST[s/task_id/1/] The task cancellation command supports the same task selection parameters as the list tasks command, so multiple tasks can be cancelled at the same time. For example, the following command will cancel all reindex tasks running on the @@ -217,7 +216,7 @@ a the client that started them: -------------------------------------------------- curl -i -H "X-Opaque-Id: 123456" "http://localhost:9200/_tasks?group_by=parents" -------------------------------------------------- -// NOTCONSOLE +//NOTCONSOLE The result will look similar to the following: @@ -260,8 +259,7 @@ content-length: 831 } } -------------------------------------------------- -// NOTCONSOLE - +//NOTCONSOLE <1> id as a part of the response header <2> id for the tasks that was initiated by the REST request <3> the child task of the task initiated by the REST request diff --git a/docs/reference/docs/delete-by-query.asciidoc b/docs/reference/docs/delete-by-query.asciidoc index 6edc453903d..93a365623fc 100644 --- a/docs/reference/docs/delete-by-query.asciidoc +++ b/docs/reference/docs/delete-by-query.asciidoc @@ -304,6 +304,7 @@ You can fetch the status of any running delete-by-query requests with the GET _tasks?detailed=true&actions=*/delete/byquery -------------------------------------------------- // CONSOLE +// TEST[skip:No tasks to retrieve] The responses looks like: @@ -344,9 +345,7 @@ The responses looks like: } } -------------------------------------------------- -// NOTCONSOLE -// We can't test tasks output - +// TESTRESPONSE <1> this object contains the actual status. It is just like the response json with the important addition of the `total` field. `total` is the total number of operations that the reindex expects to perform. You can estimate the @@ -357,10 +356,9 @@ With the task id you can look up the task directly: [source,js] -------------------------------------------------- -GET /_tasks/task_id +GET /_tasks/r1A2WoRbTwKZ516z6NEs5A:36619 -------------------------------------------------- // CONSOLE -// TEST[s/task_id/node_id:1/] // TEST[catch:missing] The advantage of this API is that it integrates with `wait_for_completion=false` @@ -375,16 +373,15 @@ you to delete that document. [[docs-delete-by-query-cancel-task-api]] === Works with the Cancel Task API -Any Delete By Query can be canceled using the <>: +Any Delete By Query can be canceled using the <>: [source,js] -------------------------------------------------- -POST _tasks/task_id/_cancel +POST _tasks/r1A2WoRbTwKZ516z6NEs5A:36619/_cancel -------------------------------------------------- -// TEST[s/task_id/node_id:1/] // CONSOLE -The `task_id` can be found using the tasks API above. +The task ID can be found using the <>. Cancellation should happen quickly but might take a few seconds. The task status API above will continue to list the task until it is wakes to cancel itself. @@ -399,12 +396,11 @@ using the `_rethrottle` API: [source,js] -------------------------------------------------- -POST _delete_by_query/task_id/_rethrottle?requests_per_second=-1 +POST _delete_by_query/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1 -------------------------------------------------- -// TEST[s/task_id/node_id:1/] // CONSOLE -The `task_id` can be found using the tasks API above. +The task ID can be found using the <>. Just like when setting it on the `_delete_by_query` API `requests_per_second` can be either `-1` to disable throttling or any decimal number diff --git a/docs/reference/docs/reindex.asciidoc b/docs/reference/docs/reindex.asciidoc index e6a47e0a398..6a9d89b9242 100644 --- a/docs/reference/docs/reindex.asciidoc +++ b/docs/reference/docs/reindex.asciidoc @@ -692,6 +692,7 @@ You can fetch the status of all running reindex requests with the GET _tasks?detailed=true&actions=*reindex -------------------------------------------------- // CONSOLE +// TEST[skip:No tasks to retrieve] The response looks like: @@ -726,32 +727,36 @@ The response looks like: "bulk": 0, "search": 0 }, - "throttled_millis": 0 + "throttled_millis": 0, + "requests_per_second": -1, + "throttled_until_millis": 0 }, - "description" : "" + "description" : "", + "start_time_in_millis": 1535149899665, + "running_time_in_nanos": 5926916792, + "cancellable": true, + "headers": {} } } } } } -------------------------------------------------- -// NOTCONSOLE -// We can't test tasks output - +// TESTRESPONSE <1> this object contains the actual status. It is identical to the response JSON except for the important addition of the `total` field. `total` is the total number of operations that the `_reindex` expects to perform. You can estimate the progress by adding the `updated`, `created`, and `deleted` fields. The request will finish when their sum is equal to the `total` field. -With the task id you can look up the task directly: +With the task id you can look up the task directly. The following example +retrieves information about the task `r1A2WoRbTwKZ516z6NEs5A:36619`: [source,js] -------------------------------------------------- -GET /_tasks/task_id +GET /_tasks/r1A2WoRbTwKZ516z6NEs5A:36619 -------------------------------------------------- // CONSOLE -// TEST[s/task_id/node_id:1/] // TEST[catch:missing] The advantage of this API is that it integrates with `wait_for_completion=false` @@ -766,16 +771,16 @@ you to delete that document. [[docs-reindex-cancel-task-api]] === Works with the Cancel Task API -Any Reindex can be canceled using the <>: +Any Reindex can be canceled using the <>. For +example: [source,js] -------------------------------------------------- -POST _tasks/task_id/_cancel +POST _tasks/r1A2WoRbTwKZ516z6NEs5A:36619/_cancel -------------------------------------------------- // CONSOLE -// TEST[s/task_id/node_id:1/] -The `task_id` can be found using the Tasks API. +The task ID can be found using the <>. Cancelation should happen quickly but might take a few seconds. The Tasks API will continue to list the task until it wakes to cancel itself. @@ -790,12 +795,11 @@ the `_rethrottle` API: [source,js] -------------------------------------------------- -POST _reindex/task_id/_rethrottle?requests_per_second=-1 +POST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1 -------------------------------------------------- // CONSOLE -// TEST[s/task_id/node_id:1/] -The `task_id` can be found using the Tasks API above. +The task ID can be found using the <>. Just like when setting it on the Reindex API, `requests_per_second` can be either `-1` to disable throttling or any decimal number diff --git a/docs/reference/docs/update-by-query.asciidoc b/docs/reference/docs/update-by-query.asciidoc index 6e7cfbd2b79..bef531d8de2 100644 --- a/docs/reference/docs/update-by-query.asciidoc +++ b/docs/reference/docs/update-by-query.asciidoc @@ -359,6 +359,7 @@ You can fetch the status of all running update-by-query requests with the GET _tasks?detailed=true&actions=*byquery -------------------------------------------------- // CONSOLE +// TEST[skip:No tasks to retrieve] The responses looks like: @@ -392,7 +393,7 @@ The responses looks like: "retries": { "bulk": 0, "search": 0 - } + }, "throttled_millis": 0 }, "description" : "" @@ -402,8 +403,7 @@ The responses looks like: } } -------------------------------------------------- -// NOTCONSOLE -// We can't test tasks output +// TESTRESPONSE <1> this object contains the actual status. It is just like the response json with the important addition of the `total` field. `total` is the total number @@ -411,14 +411,14 @@ of operations that the reindex expects to perform. You can estimate the progress by adding the `updated`, `created`, and `deleted` fields. The request will finish when their sum is equal to the `total` field. -With the task id you can look up the task directly: +With the task id you can look up the task directly. The following example +retrieves information about task `r1A2WoRbTwKZ516z6NEs5A:36619`: [source,js] -------------------------------------------------- -GET /_tasks/task_id +GET /_tasks/r1A2WoRbTwKZ516z6NEs5A:36619 -------------------------------------------------- // CONSOLE -// TEST[s/task_id/node_id:1/] // TEST[catch:missing] The advantage of this API is that it integrates with `wait_for_completion=false` @@ -437,12 +437,11 @@ Any Update By Query can be canceled using the <>: [source,js] -------------------------------------------------- -POST _tasks/task_id/_cancel +POST _tasks/r1A2WoRbTwKZ516z6NEs5A:36619/_cancel -------------------------------------------------- // CONSOLE -// TEST[s/task_id/node_id:1/] -The `task_id` can be found using the tasks API above. +The task ID can be found using the <>. Cancellation should happen quickly but might take a few seconds. The task status API above will continue to list the task until it is wakes to cancel itself. @@ -457,12 +456,11 @@ using the `_rethrottle` API: [source,js] -------------------------------------------------- -POST _update_by_query/task_id/_rethrottle?requests_per_second=-1 +POST _update_by_query/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1 -------------------------------------------------- // CONSOLE -// TEST[s/task_id/node_id:1/] -The `task_id` can be found using the tasks API above. +The task ID can be found using the <>. Just like when setting it on the `_update_by_query` API `requests_per_second` can be either `-1` to disable throttling or any decimal number