[DOCS] Clarifies examples in reindex and task APIs (#33143)
This commit is contained in:
Lisa Cawley
GitHub
parent
13af5d5d7f
commit
a4cf4ca585
|
|
@ -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 <<cluster-nodes>> 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
|
||||
|
|
|
|||
|
|
@ -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 <<tasks,Task Cancel API>>:
|
||||
Any Delete By Query can be canceled using the <<tasks,task cancel API>>:
|
||||
|
||||
[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 <<tasks,tasks API>>.
|
||||
|
||||
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 <<tasks,tasks API>>.
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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 <<tasks,Task Cancel API>>:
|
||||
Any Reindex can be canceled using the <<task-cancellation,Task Cancel API>>. 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 <<tasks,Tasks API>>.
|
||||
|
||||
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 <<tasks,tasks API>>.
|
||||
|
||||
Just like when setting it on the Reindex API, `requests_per_second`
|
||||
can be either `-1` to disable throttling or any decimal number
|
||||
|
|
|
|||
|
|
@ -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 <<tasks,Task Cancel API>>:
|
|||
|
||||
[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 <<tasks,tasks API>>.
|
||||
|
||||
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 <<tasks, tasks API>>.
|
||||
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue