mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-06 13:08:29 +00:00
6fd7ea71f1
This further applies the pattern set in #34125 to reduce copy-and-paste in the multi-document CRUD portion of the High Level REST Client docs. It also adds line wraps to snippets that are too wide to fit into the box when rendered in the docs, following up on the work started in #34163.
132 lines
4.9 KiB
Plaintext
132 lines
4.9 KiB
Plaintext
--
|
||
: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 size.
|
||
|
||
["source","java",subs="attributes,callouts,macros"]
|
||
--------------------------------------------------
|
||
include-tagged::{doc-tests-file}[{api}-request-size]
|
||
--------------------------------------------------
|
||
<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
|