_update_by_query finds multiple documents matching a query and applies an update script to each one. It is useful when a shared data change affects a set of documents, rather than a single document. section 5.4 section 5.4.7
Updating matching movies
Suppose movies containing actor Al Pacino should also identify him as an Oscar winner. A match query selects those movies, and a Painless script adds "Oscar Winner Al Pacino" before removing the old actor value. The endpoint is POST movies/_update_by_query. section 5.4.7
Listing 5.34 Updating a document using a query method
POST movies/_update_by_query #1
{
"query": { #2
"match": {
"actors": "Al Pacino"
}
},
"script": { #3
"source": """
ctx._source.actors.add('Oscar Winner Al Pacino');
ctx._source.actors.remove(ctx._source.actors.indexOf('Al Pacino'))
""",
"lang": "painless"
}
}
Run the request against the movies index; the query selects matching documents and the script changes each selected document's actors field. section 5.4.7
The operation proceeds across matching documents:
- Elasticsearch parses the query and identifies shards that may contain matches. section 5.4.7
- Each shard runs the query, and the script executes for every matched document. section 5.4.7
- Elasticsearch checks the document version before updating; a mismatch can trigger a retry. section 5.4.7
- Each successful change is applied in memory and re-indexed, while an individual failure is logged without stopping all remaining updates. section 5.4.7
