OpenSearch/docs/java-rest/high-level/document/delete-by-query.asciidoc

[[java-rest-high-document-delete-by-query]]
=== Delete By Query API

[[java-rest-high-document-delete-by-query-request]]
==== Delete By Query Request

A `DeleteByQueryRequest` 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 `DeleteByQueryRequest` looks like:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-request]
--------------------------------------------------
<1> Creates the `DeleteByQueryRequest` on a set of indices.

By default version conflicts abort the `DeleteByQueryRequest` process but you can just count them by settings it to
`proceed` in the request body

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-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}/CRUDDocumentationIT.java[delete-by-query-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 size.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-request-size]
--------------------------------------------------
<1> Only copy 10 documents

By default `DeleteByQueryRequest` uses batches of 1000. You can change the batch size with `setBatchSize`.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-request-scrollSize]
--------------------------------------------------
<1> Use batches of 100 documents

`DeleteByQueryRequest` also helps in automatically parallelizing using `sliced-scroll` to
slice on `_uid`. Use `setSlices` to specify the number of slices to use.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-request-slices]
--------------------------------------------------
<1> set number of slices to use

`DeleteByQueryRequest` uses the `scroll` parameter to control how long it keeps the "search context" alive.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-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}/CRUDDocumentationIT.java[delete-by-query-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}/CRUDDocumentationIT.java[delete-by-query-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}/CRUDDocumentationIT.java[delete-by-query-request-refresh]
--------------------------------------------------
<1> Refresh index after calling delete by query

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-request-indicesOptions]
--------------------------------------------------
<1> Set indices options


[[java-rest-high-document-delete-by-query-sync]]
==== Synchronous Execution

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-execute]
--------------------------------------------------

[[java-rest-high-document-delete-by-query-async]]
==== Asynchronous Execution

The asynchronous execution of an delete by query request requires both the `DeleteByQueryRequest`
instance and an `ActionListener` instance to be passed to the asynchronous
method:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-execute-async]
--------------------------------------------------
<1> The `DeleteByQueryRequest` to execute and the `ActionListener` to use when
the execution completes

The asynchronous method does not block and returns immediately. Once it is
completed the `ActionListener` is called back using the `onResponse` method
if the execution successfully completed or using the `onFailure` method if
it failed.

A typical listener for `BulkByScrollResponse` looks like:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-execute-listener]
--------------------------------------------------
<1> Called when the execution is successfully completed. The response is
provided as an argument and contains a list of individual results for each
operation that was executed. Note that one or more operations might have
failed while the others have been successfully executed.
<2> Called when the whole `DeleteByQueryRequest` fails. In this case the raised
exception is provided as an argument and no operation has been executed.

[[java-rest-high-document-delete-by-query-execute-listener-response]]
==== Delete By Query Response

The returned `BulkByScrollResponse` 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}/CRUDDocumentationIT.java[delete-by-query-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