Path parameters

  • indexstring | array[string] Required

    A comma-separated list of data streams, indices, and aliases to search. It supports wildcards (*). To search all data streams or indices, omit this parameter or use * or _all.

Query parameters

  • allow_no_indicesboolean

    If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.

  • analyzerstring

    The analyzer to use for the query string. This parameter can be used only when the q query string parameter is specified.

  • analyze_wildcardboolean

    If true, wildcard and prefix queries are analyzed. This parameter can be used only when the q query string parameter is specified.

  • conflictsstring

    The preferred behavior when update by query hits version conflicts: abort or proceed.

    Supported values include:

    • abort: Stop reindexing if there are conflicts.
    • proceed: Continue reindexing even if there are conflicts.

    Values are abort or proceed.

  • default_operatorstring

    The default operator for query string query: AND or OR. This parameter can be used only when the q query string parameter is specified.

    Values are and, AND, or, or OR.

  • dfstring

    The field to use as default where no field prefix is given in the query string. This parameter can be used only when the q query string parameter is specified.

  • expand_wildcardsstring | array[string]

    The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. It supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.

    Supported values include:

    • all: Match any data stream or index, including hidden ones.
    • open: Match open, non-hidden indices. Also matches any non-hidden data stream.
    • closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
    • hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
    • none: Wildcard expressions are not accepted.

    Values are all, open, closed, hidden, or none.

  • fromnumber

    Skips the specified number of documents.

  • ignore_unavailableboolean

    If false, the request returns an error if it targets a missing or closed index.

  • lenientboolean

    If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can be used only when the q query string parameter is specified.

  • max_docsnumber

    The maximum number of documents to process. It defaults to all documents. When set to a value less then or equal to scroll_size then a scroll will not be used to retrieve the results for the operation.

  • pipelinestring

    The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to _none disables the default ingest pipeline for this request. If a final pipeline is configured it will always run, regardless of the value of this parameter.

  • preferencestring

    The node or shard the operation should be performed on. It is random by default.

  • qstring

    A query in the Lucene query string syntax.

  • refreshboolean

    If true, Elasticsearch refreshes affected shards to make the operation visible to search after the request completes. This is different than the update API's refresh parameter, which causes just the shard that received the request to be refreshed.

  • request_cacheboolean

    If true, the request cache is used for this request. It defaults to the index-level setting.

  • requests_per_secondnumber

    The throttle for this request in sub-requests per second.

  • routingstring

    A custom value used to route operations to a specific shard.

  • scrollstring

    The period to retain the search context for scrolling.

    Values are -1 or 0.

  • scroll_sizenumber

    The size of the scroll request that powers the operation.

  • search_timeoutstring

    An explicit timeout for each search request. By default, there is no timeout.

    Values are -1 or 0.

  • search_typestring

    The type of the search operation. Available options include query_then_fetch and dfs_query_then_fetch.

    Supported values include:

    • query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.
    • dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.

    Values are query_then_fetch or dfs_query_then_fetch.

  • slicesnumber | string

    The number of slices this task should be divided into.

    Value is auto.

  • sortarray[string]

    A comma-separated list of : pairs.

  • statsarray[string]

    The specific tag of the request for logging and statistical purposes.

  • terminate_afternumber

    The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.

    IMPORTANT: Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers.

  • timeoutstring

    The period each update request waits for the following operations: dynamic mapping updates, waiting for active shards. By default, it is one minute. This guarantees Elasticsearch waits for at least the timeout before failing. The actual wait time could be longer, particularly when multiple waits occur.

    Values are -1 or 0.

  • versionboolean

    If true, returns the document version as part of a hit.

  • version_typeboolean

    Should the document increment the version number (internal) on hit or not (reindex)

  • wait_for_active_shardsnumber | string

    The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1). The timeout parameter controls how long each write request waits for unavailable shards to become available. Both work exactly the way they work in the bulk API.

    Values are all or index-setting.

  • wait_for_completionboolean

    If true, the request blocks until the operation is complete. If false, Elasticsearch performs some preflight checks, launches the request, and returns a task ID that 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}.

application/json

Body

  • max_docsnumber

    The maximum number of documents to update.

  • queryobject

    An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

    External documentation
  • scriptobject
    Hide script attributes Show script attributes object
    • sourcestring

      The script source.

    • idstring
    • paramsobject

      Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

      Hide params attribute Show params attribute object
      • *object Additional properties

    • langstring

      Any of:
      ScriptLanguagestringScriptLanguagestring

      Values are painless, expression, mustache, or java.

    • optionsobject
      Hide options attribute Show options attribute object
      • *string Additional properties
  • sliceobject
    Hide slice attributes Show slice attributes object
    • fieldstring

      Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

    • idstring Required
    • maxnumber Required
  • conflictsstring

    Values are abort or proceed.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • batchesnumber

      The number of scroll responses pulled back by the update by query.

    • failuresarray[object]

      Array of failures if there were any unrecoverable errors during the process. If this is non-empty then the request ended because of those failures. Update by query is implemented using batches. Any failure causes the entire process to end, but all failures in the current batch are collected into the array. You can use the conflicts option to prevent reindex from ending when version conflicts occur.

      Hide failures attributes Show failures attributes object
      • causeobject Required
        Hide cause attributes Show cause attributes object
        • typestring Required

          The type of error

        • reasonstring

          A human-readable explanation of the error, in English.

        • stack_tracestring

          The server stack trace. Present only if the error_trace=true parameter was sent with the request.

        • caused_byobject
        • root_causearray[object]
        • suppressedarray[object]
      • idstring Required
      • indexstring Required
      • statusnumber Required
    • noopsnumber

      The number of documents that were ignored because the script used for the update by query returned a noop value for ctx.op.

    • deletednumber

      The number of documents that were successfully deleted.

    • requests_per_secondnumber

      The number of requests per second effectively run during the update by query.

    • retriesobject
      Hide retries attributes Show retries attributes object
      • bulknumber Required

        The number of bulk actions retried.

      • searchnumber Required

        The number of search actions retried.

    • taskstring | number

      One of:
      TaskIdstringTaskIdnumber
    • timed_outboolean

      If true, some requests timed out during the update by query.

    • tooknumber

      Time unit for milliseconds

    • totalnumber

      The number of documents that were successfully processed.

    • updatednumber

      The number of documents that were successfully updated.

    • version_conflictsnumber

      The number of version conflicts that the update by query hit.

    • throttledstring

      A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

    • throttled_millisnumber

      Time unit for milliseconds

    • throttled_untilstring

      A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

    • throttled_until_millisnumber

      Time unit for milliseconds

POST /{index}/_update_by_query
curl \
 --request POST 'http://api.example.com/{index}/_update_by_query' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"query\": { \n    \"term\": {\n      \"user.id\": \"kimchy\"\n    }\n  }\n}"'
Request examples
Run `POST my-index-000001/_update_by_query?conflicts=proceed` to update documents that match a query.
{
  "query": { 
    "term": {
      "user.id": "kimchy"
    }
  }
}
Run `POST my-index-000001/_update_by_query` with a script to update the document source. It increments the `count` field for all documents with a `user.id` of `kimchy` in `my-index-000001`.
{
  "script": {
    "source": "ctx._source.count++",
    "lang": "painless"
  },
  "query": {
    "term": {
      "user.id": "kimchy"
    }
  }
}
Run `POST my-index-000001/_update_by_query` to slice an update by query manually. Provide a slice ID and total number of slices to each request.
{
  "slice": {
    "id": 0,
    "max": 2
  },
  "script": {
    "source": "ctx._source['extra'] = 'test'"
  }
}
Run `POST my-index-000001/_update_by_query?refresh&slices=5` to use automatic slicing. It automatically parallelizes using sliced scroll to slice on `_id`.
{
  "script": {
    "source": "ctx._source['extra'] = 'test'"
  }
}