Delete documents Added in 5.0.0

POST /{index}/_delete_by_query

Deletes documents that match the specified query.

Path parameters

  • index string | array[string] Required

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

Query parameters

  • 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.

  • analyzer string

    Analyzer to use for the query string.

  • If true, wildcard and prefix queries are analyzed.

  • What to do if delete by query hits version conflicts: abort or proceed.

    Values are abort or proceed.

  • The default operator for query string query: AND or OR.

    Values are and, AND, or, or OR.

  • df string

    Field to use as default where no field prefix is given in the query string.

  • expand_wildcards string | array[string]

    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. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.

  • from number

    Starting offset (default: 0)

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

  • lenient boolean

    If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.

  • max_docs number

    Maximum number of documents to process. Defaults to all documents.

  • Specifies the node or shard the operation should be performed on. Random by default.

  • refresh boolean

    If true, Elasticsearch refreshes all shards involved in the delete by query after the request completes.

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

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

  • routing string

    Custom value used to route operations to a specific shard.

  • q string

    Query in the Lucene query string syntax.

  • scroll string

    Period to retain the search context for scrolling.

  • Size of the scroll request that powers the operation.

  • Explicit timeout for each search request. Defaults to no timeout.

  • The type of the search operation. Available options: query_then_fetch, dfs_query_then_fetch.

    Values are query_then_fetch or dfs_query_then_fetch.

  • slices number | string

    The number of slices this task should be divided into.

  • sort array[string]

    A comma-separated list of : pairs.

  • stats array[string]

    Specific tag of the request for logging and statistical purposes.

  • 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. 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.

  • timeout string

    Period each deletion request waits for active shards.

  • version boolean

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

  • wait_for_active_shards number | 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).

  • If true, the request blocks until the operation is complete.

application/json

Body Required

  • max_docs number

    The maximum number of documents to delete.

  • query object

    Additional properties are allowed.

  • slice object

    Additional properties are allowed.

    Hide slice attributes Show slice attributes object
    • field string

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

    • id string Required
    • max number Required

Responses

POST /{index}/_delete_by_query
curl \
 -X POST http://api.example.com/{index}/_delete_by_query \
 -H "Content-Type: application/json" \
 -d '{"max_docs":42.0,"query":{},"slice":{"field":"string","id":"string","max":42.0}}'
Request examples
{
  "max_docs": 42.0,
  "query": {},
  "slice": {
    "field": "string",
    "id": "string",
    "max": 42.0
  }
}
Response examples (200)
{
  "batches": 42.0,
  "deleted": 42.0,
  "failures": [
    {
      "cause": {
        "type": "string",
        "reason": "string",
        "stack_trace": "string",
        "caused_by": {},
        "root_cause": [
          {}
        ],
        "suppressed": [
          {}
        ]
      },
      "id": "string",
      "index": "string",
      "status": 42.0,
      "type": "string"
    }
  ],
  "noops": 42.0,
  "requests_per_second": 42.0,
  "retries": {
    "bulk": 42.0,
    "search": 42.0
  },
  "slice_id": 42.0,
  "": 42.0,
  "throttled": "string",
  "throttled_until": "string",
  "timed_out": true,
  "total": 42.0,
  "version_conflicts": 42.0
}