IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Delete By Query Plugin Why Delete-By-Query is a plugin »
Elastic Docs ›Elasticsearch Plugins and Integrations [2.4] ›API Extension Plugins ›Delete By Query Plugin

Using Delete-by-Query

edit

Using Delete-by-Query

edit

The query can either be provided using a simple query string as a parameter:

DELETE /twitter/tweet/_query?q=user:kimchy

or using the Query DSL defined within the request body:

DELETE /twitter/tweet/_query
{
  "query": { 
    "term": {
      "user": "kimchy"
    }
  }
}

The query must be passed as a value to the query key, in the same way as the search api.

Both of the above examples end up doing the same thing, which is to delete all tweets from the twitter index for the user kimchy.

Delete-by-query supports deletion across multiple indices and multiple types.

Query-string parameters

edit

The following query string parameters are supported:

q
Instead of using the Query DSL to pass a query in the request body, you can use the q query string parameter to specify a query using query_string syntax. In this case, the following additional parameters are supported: df, analyzer, default_operator, lowercase_expanded_terms, analyze_wildcard and lenient. See URI search request for details.
size
The number of hits returned by the scroll request. Defaults to 10. May also be specified in the request body.
timeout
The maximum execution time of the delete by query process. Once expired, no more documents will be deleted.
routing
A comma separated list of routing values to control which shards the delete by query request should be executed on.

When using the q parameter, the following additional parameters are supported (as explained in URI search request): df, analyzer, default_operator.

Response body

edit

The JSON response looks like this:

{
  "took" : 639,
  "timed_out" : false,
  "_indices" : {
    "_all" : {
      "found" : 5901,
      "deleted" : 5901,
      "missing" : 0,
      "failed" : 0
    },
    "twitter" : {
      "found" : 5901,
      "deleted" : 5901,
      "missing" : 0,
      "failed" : 0
    }
  },
  "failures" : [ ]
}

Internally, the query is used to execute an initial scroll request. As hits are pulled from the scroll API, they are passed to the Bulk API for deletion.

Delete by query will only delete the version of the document that was visible to search at the time the request was executed. Any documents that have been reindexed or updated during execution will not be deleted.

Since documents can be updated or deleted by external operations during the scroll-bulk process, the plugin keeps track of different counters for each index, with the totals displayed under the _all index. The counters are as follows:

found
The number of documents matching the query for the given index.
deleted
The number of documents successfully deleted for the given index.
missing
The number of documents that were missing when the plugin tried to delete them. Missing documents were present when the original query was run, but have already been deleted by another process.
failed
The number of documents that failed to be deleted for the given index. A document may fail to be deleted if it has been updated to a new version by another process, or if the shard containing the document has gone missing due to hardware failure, for example.
« Delete By Query Plugin Why Delete-By-Query is a plugin »