|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: Rethrottle |
| 4 | +parent: Tasks API |
| 5 | +nav_order: 40 |
| 6 | +--- |
| 7 | + |
| 8 | +# Rethrottle |
| 9 | + |
| 10 | +You can use the following APIs to dynamically change the `requests_per_second` for [`_reindex`]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/), [`_update_by_query`]({{site.url}}{{site.baseurl}}/api-reference/document-apis/update-by-query/), or [`_delete_by_query`]({{site.url}}{{site.baseurl}}/api-reference/document-apis/delete-by-query/) operations that are already running. |
| 11 | + |
| 12 | +## Endpoints |
| 13 | + |
| 14 | +```json |
| 15 | +POST /_delete_by_query/{task_id}/_rethrottle |
| 16 | +POST /_reindex/{task_id}/_rethrottle |
| 17 | +POST /_update_by_query/{task_id}/_rethrottle |
| 18 | +``` |
| 19 | + |
| 20 | +## Path parameters |
| 21 | + |
| 22 | +Parameter | Data type | Description |
| 23 | +:--- | :--- | :--- |
| 24 | +`task_id` | String | The unique identifier for the running task that you want to rethrottle. |
| 25 | + |
| 26 | +## Query parameters |
| 27 | + |
| 28 | +Parameter | Data type | Description |
| 29 | +:--- | :--- | :--- |
| 30 | +`requests_per_second` | Float | The new throttle value to apply to the task. Use `-1` to disable throttling. Optional. |
| 31 | + |
| 32 | +### Example request: Rethrottle a running delete by query task |
| 33 | + |
| 34 | +```json |
| 35 | +POST /_delete_by_query/<YOUR_TASK_ID>/_rethrottle?requests_per_second=10 |
| 36 | +``` |
| 37 | +{% include copy-curl.html %} |
| 38 | + |
| 39 | + |
| 40 | +### Example request: Rethrottle a running reindex task |
| 41 | + |
| 42 | +```json |
| 43 | +POST /_reindex/<YOUR_TASK_ID>/_rethrottle?requests_per_second=20 |
| 44 | +``` |
| 45 | +{% include copy-curl.html %} |
| 46 | + |
| 47 | +### Example request: Rethrottle a running update by query task |
| 48 | + |
| 49 | +```json |
| 50 | +POST /_update_by_query/<YOUR_TASK_ID>/_rethrottle?requests_per_second=5 |
| 51 | +``` |
| 52 | +{% include copy-curl.html %} |
| 53 | + |
| 54 | +## Example response |
| 55 | + |
| 56 | +The following response provides details regarding the active `update_by_query` task: |
| 57 | + |
| 58 | +``` |
| 59 | +{ |
| 60 | + "nodes": { |
| 61 | + "bvv8SKpiRhOhF9_Bu8gZ7w": { |
| 62 | + "name": "opensearch-node1", |
| 63 | + "transport_address": "172.18.0.4:9300", |
| 64 | + "host": "172.18.0.4", |
| 65 | + "ip": "172.18.0.4:9300", |
| 66 | + "roles": [ |
| 67 | + "cluster_manager", |
| 68 | + "data", |
| 69 | + "ingest", |
| 70 | + "remote_cluster_client" |
| 71 | + ], |
| 72 | + "attributes": { |
| 73 | + "shard_indexing_pressure_enabled": "true" |
| 74 | + }, |
| 75 | + "tasks": { |
| 76 | + "bvv8SKpiRhOhF9_Bu8gZ7w:640": { |
| 77 | + "node": "bvv8SKpiRhOhF9_Bu8gZ7w", |
| 78 | + "id": 640, |
| 79 | + "type": "transport", |
| 80 | + "action": "indices:data/write/update/byquery", |
| 81 | + "status": { |
| 82 | + "total": 4785, |
| 83 | + "updated": 1000, |
| 84 | + "created": 0, |
| 85 | + "deleted": 0, |
| 86 | + "batches": 1, |
| 87 | + "version_conflicts": 0, |
| 88 | + "noops": 0, |
| 89 | + "retries": { |
| 90 | + "bulk": 0, |
| 91 | + "search": 0 |
| 92 | + }, |
| 93 | + "throttled_millis": 0, |
| 94 | + "requests_per_second": 50, |
| 95 | + "throttled_until_millis": 2146 |
| 96 | + }, |
| 97 | + "description": "update-by-query [test-rethrottle] updated with Script{type=inline, lang='painless', idOrCode='ctx._source.new_field = 'updated'', options={}, params={}}", |
| 98 | + "start_time_in_millis": 1751310547697, |
| 99 | + "running_time_in_nanos": 9567425129, |
| 100 | + "cancellable": true, |
| 101 | + "cancelled": false, |
| 102 | + "headers": { |
| 103 | + "X-Opaque-Id": "1b911516-44cd-4920-8c1e-79368ea7cdfd" |
| 104 | + }, |
| 105 | + "resource_stats": { |
| 106 | + "average": { |
| 107 | + "cpu_time_in_nanos": 0, |
| 108 | + "memory_in_bytes": 0 |
| 109 | + }, |
| 110 | + "total": { |
| 111 | + "cpu_time_in_nanos": 0, |
| 112 | + "memory_in_bytes": 0 |
| 113 | + }, |
| 114 | + "min": { |
| 115 | + "cpu_time_in_nanos": 0, |
| 116 | + "memory_in_bytes": 0 |
| 117 | + }, |
| 118 | + "max": { |
| 119 | + "cpu_time_in_nanos": 0, |
| 120 | + "memory_in_bytes": 0 |
| 121 | + }, |
| 122 | + "thread_info": { |
| 123 | + "thread_executions": 0, |
| 124 | + "active_threads": 0 |
| 125 | + } |
| 126 | + } |
| 127 | + } |
| 128 | + } |
| 129 | + } |
| 130 | + } |
| 131 | +} |
| 132 | +``` |
| 133 | + |
| 134 | +## Response body fields |
| 135 | + |
| 136 | +The response provides detailed task- and node-level information about the rethrottled operation. |
| 137 | + |
| 138 | +| Field | Data type | Description | |
| 139 | +| :--- | :--- | :--- | |
| 140 | +| `nodes` | Object | A map of node IDs to details about the task on each node. | |
| 141 | +| `nodes.<node_id>.name` | String | The name of the node on which the task is running. | |
| 142 | +| `nodes.<node_id>.transport_address` | String | The transport address of the node. | |
| 143 | +| `nodes.<node_id>.host` | String | The host IP address. | |
| 144 | +| `nodes.<node_id>.ip` | String | The IP address and port. | |
| 145 | +| `nodes.<node_id>.roles` | Array | The roles assigned to the node. | |
| 146 | +| `nodes.<node_id>.attributes` | Object | Node-level attributes. | |
| 147 | +| `nodes.<node_id>.tasks` | Object | A map of task IDs to detailed information about each task. | |
| 148 | +| `nodes.<node_id>.tasks.<task_id>.type` | String | The task type, such as `transport`. | |
| 149 | +| `nodes.<node_id>.tasks.<task_id>.action` | String | The specific action being performed (for example, `reindex`). | |
| 150 | +| `nodes.<node_id>.tasks.<task_id>.status` | Object | The current status of the task. | |
| 151 | +| `nodes.<node_id>.tasks.<task_id>.status.total` | Integer | The total number of documents to process. | |
| 152 | +| `nodes.<node_id>.tasks.<task_id>.status.created` | Integer | The number of documents created. | |
| 153 | +| `nodes.<node_id>.tasks.<task_id>.status.updated` | Integer | The number of documents updated. | |
| 154 | +| `nodes.<node_id>.tasks.<task_id>.status.deleted` | Integer | The number of documents deleted. | |
| 155 | +| `nodes.<node_id>.tasks.<task_id>.status.batches` | Integer | The number of batches processed. | |
| 156 | +| `nodes.<node_id>.tasks.<task_id>.status.version_conflicts` | Integer | The number of version conflicts. | |
| 157 | +| `nodes.<node_id>.tasks.<task_id>.status.noops` | Integer | The number of no-op updates. | |
| 158 | +| `nodes.<node_id>.tasks.<task_id>.status.retries` | Object | Retry stats for bulk and search operations. | |
| 159 | +| `nodes.<node_id>.tasks.<task_id>.status.requests_per_second` | Float | Current throttle rate in requests per second. | |
| 160 | +| `nodes.<node_id>.tasks.<task_id>.status.throttled_millis` | Integer | The time, in milliseconds, that the task was throttled. | |
| 161 | +| `nodes.<node_id>.tasks.<task_id>.status.throttled_until_millis` | Integer | The time, in milliseconds, that the task is expected to remain throttled. | |
| 162 | +| `nodes.<node_id>.tasks.<task_id>.description` | String | A human-readable description of the task. | |
| 163 | +| `nodes.<node_id>.tasks.<task_id>.start_time_in_millis` | Integer | The task start time in epoch milliseconds. | |
| 164 | +| `nodes.<node_id>.tasks.<task_id>.running_time_in_nanos` | Integer | The task runtime in nanoseconds. | |
| 165 | +| `nodes.<node_id>.tasks.<task_id>.cancellable` | Boolean | Whether the task can be canceled. | |
| 166 | +| `nodes.<node_id>.tasks.<task_id>.cancelled` | Boolean | Whether the task has been canceled. | |
| 167 | +| `nodes.<node_id>.tasks.<task_id>.headers` | Object | Optional HTTP headers associated with the task. | |
| 168 | +| `nodes.<node_id>.tasks.<task_id>.resource_stats` | Object | Statistics about resource usage. | |
0 commit comments