Skip to content

Add link to _update_by_query API examples #4705

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jul 3, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions specification/_doc_ids/table.csv
Original file line number Diff line number Diff line change
Expand Up @@ -895,6 +895,7 @@ test-grok-pattern,https://www.elastic.co/docs/api/doc/elasticsearch/operation/op
time-value,https://github.com/elastic/elasticsearch/blob/current/libs/core/src/main/java/org/elasticsearch/core/TimeValue.java,
time-zone-id,https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html,
trim-processor,https://www.elastic.co/docs/reference/enrich-processor/trim-processor,
update-by-query,https://www.elastic.co/docs/reference/elasticsearch/rest-apis/update-by-query-api,
update-dfanalytics,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ml-update-data-frame-analytics,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/update-dfanalytics.html
update-desired-nodes,https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-cluster,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/cluster.html
update-license,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-license-post,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/update-license.html
Expand Down
42 changes: 26 additions & 16 deletions specification/_global/update_by_query/UpdateByQueryRequest.ts
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,30 @@ import { Duration } from '@_types/Time'
* Any query or update failures cause the update by query request to fail and the failures are shown in the response.
* Any update requests that completed successfully still stick, they are not rolled back.
*
* **Refreshing shards**
*
* Specifying the `refresh` parameter refreshes all shards once the request completes.
* This is different to the update API's `refresh` parameter, which causes only the shard
* that received the request to be refreshed. Unlike the update API, it does not support
* `wait_for`.
*
* **Running update by query asynchronously**
*
* If the request contains `wait_for_completion=false`, Elasticsearch
* performs some preflight checks, launches the request, and returns a
* [task](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-tasks) you can use to cancel or get the status of the task.
* Elasticsearch creates a record of this task as a document at `.tasks/task/${taskId}`.
*
* **Waiting for active shards**
*
* `wait_for_active_shards` controls how many copies of a shard must be active
* before proceeding with the request. See [`wait_for_active_shards`](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-create#operation-create-wait_for_active_shards)
* for details. `timeout` controls how long each write request waits for unavailable
* shards to become available. Both work exactly the way they work in the
* [Bulk API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-bulk). Update by query uses scrolled searches, so you can also
* specify the `scroll` parameter to control how long it keeps the search context
* alive, for example `?scroll=10m`. The default is 5 minutes.
*
* **Throttling update requests**
*
* To control the rate at which update by query issues batches of update operations, you can set `requests_per_second` to any positive decimal number.
Expand Down Expand Up @@ -103,28 +127,14 @@ import { Duration } from '@_types/Time'
* * Update performance scales linearly across available resources with the number of slices.
*
* Whether query or update performance dominates the runtime depends on the documents being reindexed and cluster resources.
*
* **Update the document source**
*
* Update by query supports scripts to update the document source.
* As with the update API, you can set `ctx.op` to change the operation that is performed.
*
* Set `ctx.op = "noop"` if your script decides that it doesn't have to make any changes.
* The update by query operation skips updating the document and increments the `noop` counter.
*
* Set `ctx.op = "delete"` if your script decides that the document should be deleted.
* The update by query operation deletes the document and increments the `deleted` counter.
*
* Update by query supports only `index`, `noop`, and `delete`.
* Setting `ctx.op` to anything else is an error.
* Setting any other field in `ctx` is an error.
* This API enables you to only modify the source of matching documents; you cannot move them.
* Refer to the linked documentation for examples of how to update documents using the `_update_by_query` API:
* @rest_spec_name update_by_query
* @availability stack since=2.4.0 stability=stable
* @availability serverless stability=stable visibility=public
* @index_privileges read,write
* @doc_tag document
* @doc_id docs-update-by-query
* @ext_doc_id update-by-query
*/
export interface Request extends RequestBase {
urls: [
Expand Down
Loading