--
:api: delete-by-query
:request: DeleteByQueryRequest
:response: DeleteByQueryResponse
--

[id="{upid}-{api}"]
=== Delete By Query API

[id="{upid}-{api}-request"]
==== Delete By Query Request

A +{request}+ can be used to delete documents from an index. It requires an
existing index (or a set of indices) on which deletion is to be performed.

The simplest form of a +{request}+ looks like this and deletes all documents
in an index:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-request]
--------------------------------------------------
<1> Creates the +{request}+ on a set of indices.

By default version conflicts abort the +{request}+ process but you can just
count them with this:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-request-conflicts]
--------------------------------------------------
<1> Set `proceed` on version conflict

You can limit the documents by adding a query.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-request-query]
--------------------------------------------------
<1> Only copy documents which have field `user` set to `kimchy`

It’s also possible to limit the number of processed documents by setting `maxDocs`.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-request-maxDocs]
--------------------------------------------------
<1> Only copy 10 documents

By default +{request}+ uses batches of 1000. You can change the batch size
with `setBatchSize`.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-request-scrollSize]
--------------------------------------------------
<1> Use batches of 100 documents

+{request}+ can also be parallelized using `sliced-scroll` with `setSlices`:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-request-slices]
--------------------------------------------------
<1> set number of slices to use

+{request}+ uses the `scroll` parameter to control how long it keeps the
"search context" alive.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-request-scroll]
--------------------------------------------------
<1> set scroll time

If you provide routing then the routing is copied to the scroll query, limiting the process to the shards that match
that routing value.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-request-routing]
--------------------------------------------------
<1> set routing


==== Optional arguments
In addition to the options above the following arguments can optionally be also provided:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-request-timeout]
--------------------------------------------------
<1> Timeout to wait for the delete by query request to be performed as a `TimeValue`

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-request-refresh]
--------------------------------------------------
<1> Refresh index after calling delete by query

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-request-indicesOptions]
--------------------------------------------------
<1> Set indices options

include::../execution.asciidoc[]

[id="{upid}-{api}-response"]
==== Delete By Query Response

The returned +{response}+ contains information about the executed operations and
allows to iterate over each result as follows:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-response]
--------------------------------------------------
<1> Get total time taken
<2> Check if the request timed out
<3> Get total number of docs processed
<4> Number of docs that were deleted
<5> Number of batches that were executed
<6> Number of skipped docs
<7> Number of version conflicts
<8> Number of times request had to retry bulk index operations
<9> Number of times request had to retry search operations
<10> The total time this request has throttled itself not including the current throttle time if it is currently sleeping
<11> Remaining delay of any current throttle sleep or 0 if not sleeping
<12> Failures during search phase
<13> Failures during bulk index operation