Link Search Menu Expand Document Documentation Menu
Documentation

You're viewing version 3.1 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Rethrottle API

You can use the following APIs to dynamically change the requests_per_second for _reindex, _update_by_query, or _delete_by_query operations that are already running.

Endpoints

POST /_delete_by_query/{task_id}/_rethrottle
POST /_reindex/{task_id}/_rethrottle
POST /_update_by_query/{task_id}/_rethrottle

Path parameters

Parameter Data type Description
task_id String The unique identifier for the running task that you want to rethrottle.

Query parameters

Parameter Data type Description
requests_per_second Float The new throttle value to apply to the task. Use -1 to disable throttling. Optional.

Example request: Rethrottle a running delete by query task

POST /_delete_by_query/<YOUR_TASK_ID>/_rethrottle?requests_per_second=10

Example request: Rethrottle a running reindex task

POST /_reindex/<YOUR_TASK_ID>/_rethrottle?requests_per_second=20

Example request: Rethrottle a running update by query task

POST /_update_by_query/<YOUR_TASK_ID>/_rethrottle?requests_per_second=5

Example response

The following response provides details regarding the active update_by_query task:

{
  "nodes": {
    "bvv8SKpiRhOhF9_Bu8gZ7w": {
      "name": "opensearch-node1",
      "transport_address": "172.18.0.4:9300",
      "host": "172.18.0.4",
      "ip": "172.18.0.4:9300",
      "roles": [
        "cluster_manager",
        "data",
        "ingest",
        "remote_cluster_client"
      ],
      "attributes": {
        "shard_indexing_pressure_enabled": "true"
      },
      "tasks": {
        "bvv8SKpiRhOhF9_Bu8gZ7w:640": {
          "node": "bvv8SKpiRhOhF9_Bu8gZ7w",
          "id": 640,
          "type": "transport",
          "action": "indices:data/write/update/byquery",
          "status": {
            "total": 4785,
            "updated": 1000,
            "created": 0,
            "deleted": 0,
            "batches": 1,
            "version_conflicts": 0,
            "noops": 0,
            "retries": {
              "bulk": 0,
              "search": 0
            },
            "throttled_millis": 0,
            "requests_per_second": 50,
            "throttled_until_millis": 2146
          },
          "description": "update-by-query [test-rethrottle] updated with Script{type=inline, lang='painless', idOrCode='ctx._source.new_field = 'updated'', options={}, params={}}",
          "start_time_in_millis": 1751310547697,
          "running_time_in_nanos": 9567425129,
          "cancellable": true,
          "cancelled": false,
          "headers": {
            "X-Opaque-Id": "1b911516-44cd-4920-8c1e-79368ea7cdfd"
          },
          "resource_stats": {
            "average": {
              "cpu_time_in_nanos": 0,
              "memory_in_bytes": 0
            },
            "total": {
              "cpu_time_in_nanos": 0,
              "memory_in_bytes": 0
            },
            "min": {
              "cpu_time_in_nanos": 0,
              "memory_in_bytes": 0
            },
            "max": {
              "cpu_time_in_nanos": 0,
              "memory_in_bytes": 0
            },
            "thread_info": {
              "thread_executions": 0,
              "active_threads": 0
            }
          }
        }
      }
    }
  }
}

Response body fields

The response provides detailed task- and node-level information about the rethrottled operation.

Field Data type Description
nodes Object A map of node IDs to details about the task on each node.
nodes.<node_id>.name String The name of the node on which the task is running.
nodes.<node_id>.transport_address String The transport address of the node.
nodes.<node_id>.host String The host IP address.
nodes.<node_id>.ip String The IP address and port.
nodes.<node_id>.roles Array The roles assigned to the node.
nodes.<node_id>.attributes Object Node-level attributes.
nodes.<node_id>.tasks Object A map of task IDs to detailed information about each task.
nodes.<node_id>.tasks.<task_id>.type String The task type, such as transport.
nodes.<node_id>.tasks.<task_id>.action String The specific action being performed (for example, reindex).
nodes.<node_id>.tasks.<task_id>.status Object The current status of the task.
nodes.<node_id>.tasks.<task_id>.status.total Integer The total number of documents to process.
nodes.<node_id>.tasks.<task_id>.status.created Integer The number of documents created.
nodes.<node_id>.tasks.<task_id>.status.updated Integer The number of documents updated.
nodes.<node_id>.tasks.<task_id>.status.deleted Integer The number of documents deleted.
nodes.<node_id>.tasks.<task_id>.status.batches Integer The number of batches processed.
nodes.<node_id>.tasks.<task_id>.status.version_conflicts Integer The number of version conflicts.
nodes.<node_id>.tasks.<task_id>.status.noops Integer The number of no-op updates.
nodes.<node_id>.tasks.<task_id>.status.retries Object Retry stats for bulk and search operations.
nodes.<node_id>.tasks.<task_id>.status.requests_per_second Float Current throttle rate in requests per second.
nodes.<node_id>.tasks.<task_id>.status.throttled_millis Integer The time, in milliseconds, that the task was throttled.
nodes.<node_id>.tasks.<task_id>.status.throttled_until_millis Integer The time, in milliseconds, that the task is expected to remain throttled.
nodes.<node_id>.tasks.<task_id>.description String A human-readable description of the task.
nodes.<node_id>.tasks.<task_id>.start_time_in_millis Integer The task start time in epoch milliseconds.
nodes.<node_id>.tasks.<task_id>.running_time_in_nanos Integer The task runtime in nanoseconds.
nodes.<node_id>.tasks.<task_id>.cancellable Boolean Whether the task can be canceled.
nodes.<node_id>.tasks.<task_id>.cancelled Boolean Whether the task has been canceled.
nodes.<node_id>.tasks.<task_id>.headers Object Optional HTTP headers associated with the task.
nodes.<node_id>.tasks.<task_id>.resource_stats Object Statistics about resource usage.
350 characters left

Have a question? .

Want to contribute? or .