Throttle a reindex operation

Auth

Change the maximum number of documents to index per second for a particular reindex operation. For example, to unthrottle to unlimited documents per second:

POST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1

Rethrottling that speeds up the query takes effect immediately. Rethrottling that slows down the query will take effect after completing the current batch of documents. This behavior prevents scroll timeouts.

This API follows reindex tasks across node-shutdown relocations, so callers can keep using the original task ID throughout the lifetime of the operation. The relocated task ID is also accepted and is followed transparently. In either case, returned task IDs and timings reflect the original task, not its relocated successor.

The rethrottle may not have been applied to any tasks if either node_failures or task_failures are non-empty, or if the response contains no successfully rethrottled tasks — that is, no entries under nodes (returned with the default group_by=nodes in stack) or under tasks (returned in serverless, or in stack with group_by=none or group_by=parents).

Path parameters

task_id string required

The task identifier, returned when creating a reindex task, or by listing tasks via GET /_reindex or GET /_tasks. In stack, can be either the original task ID or the task ID of the relocated task.

Query parameters

requests_per_second number required

The maximum number of documents to index per second, across the entire reindex operation (including slices). It can be either -1 to turn off throttling or any decimal number like 1.7 or 12 to throttle to that level.

group_by enum · default: nodes

The way to group the tasks in the response. We recommend setting this to none, which provides the cleanest response format.

Supported values include:

  • nodes: Group tasks by node ID.
  • parents: Group tasks by parent task ID.
  • none: Do not group tasks.
Values: nodes parents none

Response

application/json
node_failures object[]

Node-level failures encountered while applying the rethrottle request. Will return a failed_node_exception wrapping a no_such_node_exception, if a node handling the task either never existed, or has left the cluster, and one of the following is true:

  1. The task has completed.
  2. The task cannot be found.
Note

Rethrottle handles relocations, so it should succeed if the task can be found and has not completed.

type string required

The type of error

reason union string nullable

A human-readable explanation of the error, in English.

One of: string
stack_trace string

The server stack trace. Present only if the error_trace=true parameter was sent with the request.

caused_by object
Same fields as node_failures
root_cause object[]
Same fields as node_failures
suppressed object[]
Same fields as node_failures
task_failures object[]

Per-task failures encountered while applying the rethrottle. If a rethrottle is attempted during a relocation handoff, the failure object reports status: SERVICE_UNAVAILABLE (the HTTP response itself is still 200 OK). In this case, the request can be retried until success.

task_id number required
node_id string required
status string required
reason object required
type string required

The type of error

reason union string nullable

A human-readable explanation of the error, in English.

One of: string
stack_trace string

The server stack trace. Present only if the error_trace=true parameter was sent with the request.

caused_by object
Same fields as reason in task_failures
root_cause object[]
Same fields as reason in task_failures
suppressed object[]
Same fields as reason in task_failures
nodes map string to object

Tasks grouped by node, returned only when group_by=nodes (the default).

<string> object
attributes map string to string required
host string required
ip string required
name string required
roles enum[]
Values: master data data_cold data_content data_frozen data_hot data_warm client ingest ml voting_only transform remote_cluster_client coordinating_only
transport_address string required
tasks map string to object required
<string> object
action string required
cancellable boolean required
cancelled boolean required
description string required
id number required
node string required
running_time_in_nanos number required
start_time_in_millis number required
status object required
slices object[]
slice_id number

The slice ID

batches number required

The number of scroll responses pulled back by the reindex.

created number

The number of documents that were successfully created.

deleted number required

The number of documents that were successfully deleted.

noops number required

The number of documents that were ignored because the script used for the reindex returned a noop value for ctx.op.

requests_per_second number required

The number of requests per second effectively executed during the reindex.

retries object required

The number of retries attempted by reindex. bulk is the number of bulk actions retried and search is the number of search actions retried.

bulk number required

The number of bulk actions retried.

The number of search actions retried.

throttled string
throttled_millis number required

Number of milliseconds the request slept to conform to requests_per_second.

throttled_until string
throttled_until_millis number required

This field should always be equal to zero in a _reindex response. It only has meaning when using the Task API, where it indicates the next time (in milliseconds since epoch) a throttled request will be executed again in order to conform to requests_per_second.

total number required

The number of documents that were successfully processed.

updated number

The number of documents that were successfully updated, for example, a document with same ID already existed prior to reindex updating it.

version_conflicts number required

The number of version conflicts that reindex hits.

cancelled string

The reason for cancellation if the slice was canceled

slice_id number

The slice ID

batches number required

The number of scroll responses pulled back by the reindex.

created number

The number of documents that were successfully created.

deleted number required

The number of documents that were successfully deleted.

noops number required

The number of documents that were ignored because the script used for the reindex returned a noop value for ctx.op.

requests_per_second number required

The number of requests per second effectively executed during the reindex.

retries object required

The number of retries attempted by reindex. bulk is the number of bulk actions retried and search is the number of search actions retried.

bulk number required

The number of bulk actions retried.

The number of search actions retried.

throttled string
throttled_millis number required

Number of milliseconds the request slept to conform to requests_per_second.

throttled_until string
throttled_until_millis number required

This field should always be equal to zero in a _reindex response. It only has meaning when using the Task API, where it indicates the next time (in milliseconds since epoch) a throttled request will be executed again in order to conform to requests_per_second.

total number required

The number of documents that were successfully processed.

updated number

The number of documents that were successfully updated, for example, a document with same ID already existed prior to reindex updating it.

version_conflicts number required

The number of version conflicts that reindex hits.

cancelled string

The reason for cancellation if the slice was canceled

type string required
headers object required
tasks union oneOf

The tasks that were successfully rethrottled. Always returned in serverless. Returned with group_by=none or group_by=parents in stack.

One of:
{} ReindexTask[]
action string required
cancellable boolean required
cancelled boolean required
description string required
id number required
node string required
running_time_in_nanos number required
start_time_in_millis number required
status object required
Same fields as status in tasks
type string required
headers object required