You're viewing version 1.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.
Update by query
Introduced 1.0
You can include a query and a script as part of your update request so OpenSearch can run the script to update all of the documents that match the query.
Example
POST test-index1/_update_by_query
{
"query": {
"term": {
"oldValue": 10
}
},
"script" : {
"source": "ctx._source.oldValue += params.newValue",
"lang": "painless",
"params" : {
"newValue" : 20
}
}
}
Path and HTTP methods
POST <target-index1>, <target-index2>/_update_by_query
URL parameters
All URL parameters are optional.
| Parameter | Type | Description |
|---|---|---|
| <index> | String | Comma-separated list of indices to update. To update all indices, use * or omit this parameter. |
| allow_no_indices | Boolean | Whether to ignore wildcards that don’t match any indices. Default is true. |
| analyzer | String | Analyzer to use in the query string. |
| analyze_wildcard | Boolean | Whether the update operation should include wildcard and prefix queries in the analysis. Default is false. |
| conflicts | String | Indicates to OpenSearch what should happen if the update by query operation runs into a version conflict. Valid options are abort and proceed. Default is abort. |
| default_operator | String | Indicates whether the default operator for a string query should be AND or OR. Default is OR. |
| df | String | The default field if a field prefix is not provided in the query string. |
| expand_wildcards | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are all (match any index), open (match open, non-hidden indices), closed (match closed, non-hidden indices), hidden (match hidden indices), and none (deny wildcard expressions). Default is open. |
| from | Integer | The starting index to search from. Default is 0. |
| ignore_unavailable | Boolean | Whether to exclude missing or closed indices in the response. Default is false. |
| lenient | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is false. |
| max_docs | Integer | How many documents the update by query operation should process at most. Default is all documents. |
| pipeline | String | ID of the pipeline to use to process documents. |
| preference | String | Specifies which shard or node OpenSearch should perform the update by query operation on. |
| q | String | Lucene query string’s query. |
| request_cache | Boolean | Specifies whether OpenSearch should use the request cache. Default is whether it’s enabled in the index’s settings. |
| refresh | Boolean | If true, OpenSearch refreshes shards to make the update by query operation available to search results. Valid options are true, false, and wait_for, which tells OpenSearch to wait for a refresh before executing the operation. Default is false. |
| requests_per_second | Integer | Specifies the request’s throttling in sub-requests per second. Default is -1, which means no throttling. |
| routing | String | Value used to route the update by query operation to a specific shard. |
| scroll | Time | How long to keep the search context open. |
| scroll_size | Integer | Size of the operation’s scroll request. Default is 1000. |
| search_type | String | Whether OpenSearch should use global term and document frequencies calculating revelance scores. Valid choices are query_then_fetch and dfs_query_then_fetch. query_then_fetch scores documents using local term and document frequencies for the shard. It’s usually faster but less accurate. dfs_query_then_fetch scores documents using global term and document frequencies across all shards. It’s usually slower but more accurate. Default is query_then_fetch. |
| search_timeout | Time | How long to wait until OpenSearch deems the request timed out. Default is no timeout. |
| slices | Integer | Number of sub-tasks OpenSearch should divide this task into. Default is 1, which means OpenSearch should not divide this task. |
| sort | List | A comma-separated list of <field> : <direction> pairs to sort by. |
| _source | String | Whether to include the _source field in the response. |
| _source_excludes | String | A comma-separated list of source fields to exclude from the response. |
| _source_includes | String | A comma-separated list of source fields to include in the response. |
| stats | String | Value to associate with the request for additional logging. |
| terminate_after | Integer | The maximum number of documents OpenSearch should process before terminating the request. |
| timeout | Time | How long the operation should wait from a response from active shards. Default is 1m. |
| version | Boolean | Whether to include the document version as a match. |
| wait_for_active_shards | String | The number of shards that must be active before OpenSearch executes the operation. Valid values are all or any integer up to the total number of shards in the index. Default is 1, which is the primary shard. |
Request body
To update your indices and documents by query, you must include a query and a script in the request body that OpenSearch can run to update your documents. If you don’t specify a query, then every document in the index gets updated.
{
"query": {
"term": {
"oldValue": 20
}
},
"script" : {
"source": "ctx._source.oldValue += params.newValue",
"lang": "painless",
"params" : {
"newValue" : 10
}
}
}
Response
{
"took": 21,
"timed_out": false,
"total": 1,
"updated": 1,
"deleted": 0,
"batches": 1,
"version_conflicts": 0,
"noops": 0,
"retries": {
"bulk": 0,
"search": 0
},
"throttled_millis": 0,
"requests_per_second": -1.0,
"throttled_until_millis": 0,
"failures": []
}
Response body fields
| Field | Description |
|---|---|
| took | The amount of time in milliseconds OpenSearch needed to complete the operation. |
| timed_out | Whether any update requests during the operation timed out. |
| total | Total number of documents processed. |
| updated | Total number of documents updated. |
| batches | Number of scroll responses the request processed. |
| version_conflicts | Number of conflicts the request ran into. |
| noops | How many update requests OpenSearch ignored during the operation. This field always returns 0. |
| retries | The number of bulk and search retry requests. |
| throttled_millis | Number of throttled milliseconds during the request. |
| requests_per_second | Number of requests executed per second during the operation. |
| throttled_until_millis | The amount of time until OpenSearch executes the next throttled request. Always equal to 0 in an update by query request. |
| failures | Any failures that occur during the request. |