* [DOCS] Reformats delete by query API (#46051) * Reformats delete by query API * Update docs/reference/docs/delete-by-query.asciidoc Co-Authored-By: James Rodewig <james.rodewig@elastic.co> * Updated common parms includes. * [DOCS] Fixed issue in Common Parms.
This commit is contained in:
debadair
GitHub
parent
cf8a4171e1
commit
bd50845855
|
|
@ -1,14 +1,16 @@
|
|||
[[docs-delete-by-query]]
|
||||
=== Delete By Query API
|
||||
=== Delete by query API
|
||||
++++
|
||||
<titleabbrev>Delete by query</titleabbrev>
|
||||
++++
|
||||
|
||||
The simplest usage of `_delete_by_query` just performs a deletion on every
|
||||
document that matches a query. Here is the API:
|
||||
Deletes documents that match the specified query.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST twitter/_delete_by_query
|
||||
POST /twitter/_delete_by_query
|
||||
{
|
||||
"query": { <1>
|
||||
"query": {
|
||||
"match": {
|
||||
"message": "some message"
|
||||
}
|
||||
|
|
@ -18,11 +20,12 @@ POST twitter/_delete_by_query
|
|||
// CONSOLE
|
||||
// TEST[setup:big_twitter]
|
||||
|
||||
<1> The query must be passed as a value to the `query` key, in the same
|
||||
way as the <<search-search,Search API>>. You can also use the `q`
|
||||
parameter in the same way as the search API.
|
||||
[[docs-delete-by-query-api-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
That will return something like this:
|
||||
`POST /<index>/_delete_by_query`
|
||||
|
||||
////
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -45,136 +48,76 @@ That will return something like this:
|
|||
}
|
||||
--------------------------------------------------
|
||||
// TESTRESPONSE[s/"took" : 147/"took" : "$body.took"/]
|
||||
////
|
||||
|
||||
`_delete_by_query` gets a snapshot of the index when it starts and deletes what
|
||||
it finds using `internal` versioning. That means that you'll get a version
|
||||
conflict if the document changes between the time when the snapshot was taken
|
||||
and when the delete request is processed. When the versions match the document
|
||||
is deleted.
|
||||
[[docs-delete-by-query-api-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
NOTE: Since `internal` versioning does not support the value 0 as a valid
|
||||
version number, documents with version equal to zero cannot be deleted using
|
||||
`_delete_by_query` and will fail the request.
|
||||
You can specify the query criteria in the request URI or the request body
|
||||
using the same syntax as the <<search-search,Search API>>.
|
||||
|
||||
During the `_delete_by_query` execution, multiple search requests are sequentially
|
||||
executed in order to find all the matching documents to delete. Every time a batch
|
||||
of documents is found, a corresponding bulk request is executed to delete all
|
||||
these documents. In case a search or bulk request got rejected, `_delete_by_query`
|
||||
relies on a default policy to retry rejected requests (up to 10 times, with
|
||||
exponential back off). Reaching the maximum retries limit causes the `_delete_by_query`
|
||||
to abort and all failures are returned in the `failures` of the response.
|
||||
The deletions that have been performed still stick. In other words, the process
|
||||
is not rolled back, only aborted. While the first failure causes the abort, all
|
||||
failures that are returned by the failing bulk request are returned in the `failures`
|
||||
element; therefore it's possible for there to be quite a few failed entities.
|
||||
When you submit a delete by query request, {es} gets a snapshot of the index
|
||||
when it begins processing the request and deletes matching documents using
|
||||
`internal` versioning. If a document changes between the time that the
|
||||
snapshot is taken and the delete operation is processed, it results in a version
|
||||
conflict and the delete operation fails.
|
||||
|
||||
If you'd like to count version conflicts rather than cause them to abort, then
|
||||
set `conflicts=proceed` on the url or `"conflicts": "proceed"` in the request body.
|
||||
NOTE: Documents with a version equal to 0 cannot be deleted using delete by
|
||||
query because `internal` versioning does not support 0 as a valid
|
||||
version number.
|
||||
|
||||
Back to the API format, this will delete tweets from the `twitter` index:
|
||||
While processing a delete by query request, {es} performs multiple search
|
||||
requests sequentially to find all of the matching documents to delete. A bulk
|
||||
delete request is performed for each batch of matching documents. If a
|
||||
search or bulk request is rejected, the requests are retried up to 10 times, with
|
||||
exponential back off. If the maximum retry limit is reached, processing halts
|
||||
and all failed requests are returned in the response. Any delete requests that
|
||||
completed successfully still stick, they are not rolled back.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST twitter/_delete_by_query?conflicts=proceed
|
||||
{
|
||||
"query": {
|
||||
"match_all": {}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[setup:twitter]
|
||||
You can opt to count version conflicts instead of halting and returning by
|
||||
setting `conflicts` to `proceeed`.
|
||||
|
||||
It's also possible to delete documents of multiple indexes at once, just like
|
||||
the search API:
|
||||
===== Refreshing shards
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST twitter,blog/_delete_by_query
|
||||
{
|
||||
"query": {
|
||||
"match_all": {}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[s/^/PUT twitter\nPUT blog\n/]
|
||||
Specifying the `refresh` parameter refreshes all shards involved in the delete
|
||||
by query once the request completes. This is different than the delete API's
|
||||
`refresh` parameter, which causes just the shard that received the delete
|
||||
request to be refreshed. Unlike the delete API, it does not support
|
||||
`wait_for`.
|
||||
|
||||
If you provide `routing` then the routing is copied to the scroll query,
|
||||
limiting the process to the shards that match that routing value:
|
||||
[[docs-delete-by-query-task-api]]
|
||||
===== Running delete by query asynchronously
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST twitter/_delete_by_query?routing=1
|
||||
{
|
||||
"query": {
|
||||
"range" : {
|
||||
"age" : {
|
||||
"gte" : 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[setup:twitter]
|
||||
If the request contains `wait_for_completion=false`, {es}
|
||||
performs some preflight checks, launches the request, and returns a
|
||||
<<docs-delete-by-query-task-api,`task`>>
|
||||
you can use to cancel or get the status of the task. {es} creates a
|
||||
record of this task as a document at `.tasks/task/${taskId}`. When you are
|
||||
done with a task, you should delete the task document so {es} can reclaim the
|
||||
space.
|
||||
|
||||
By default `_delete_by_query` uses scroll batches of 1000. You can change the
|
||||
batch size with the `scroll_size` URL parameter:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST twitter/_delete_by_query?scroll_size=5000
|
||||
{
|
||||
"query": {
|
||||
"term": {
|
||||
"user": "kimchy"
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[setup:twitter]
|
||||
|
||||
|
||||
[float]
|
||||
==== URL Parameters
|
||||
|
||||
In addition to the standard parameters like `pretty`, the delete by query API
|
||||
also supports `refresh`, `wait_for_completion`, `wait_for_active_shards`, `timeout`,
|
||||
and `scroll`.
|
||||
|
||||
Sending the `refresh` will refresh all shards involved in the delete by query
|
||||
once the request completes. This is different than the delete API's `refresh`
|
||||
parameter which causes just the shard that received the delete request
|
||||
to be refreshed. Also unlike the delete API it does not support `wait_for`.
|
||||
|
||||
If the request contains `wait_for_completion=false` then Elasticsearch will
|
||||
perform some preflight checks, launch the request, and then return a `task`
|
||||
which can be used with <<docs-delete-by-query-task-api,Tasks APIs>>
|
||||
to cancel or get the status of the task. Elasticsearch will also create a
|
||||
record of this task as a document at `.tasks/task/${taskId}`. This is yours
|
||||
to keep or remove as you see fit. When you are done with it, delete it so
|
||||
Elasticsearch can reclaim the space it uses.
|
||||
===== Waiting for active shards
|
||||
|
||||
`wait_for_active_shards` controls how many copies of a shard must be active
|
||||
before proceeding with the request. See <<index-wait-for-active-shards,here>>
|
||||
before proceeding with the request. See <<index-wait-for-active-shards>>
|
||||
for details. `timeout` controls how long each write request waits for unavailable
|
||||
shards to become available. Both work exactly how they work in the
|
||||
<<docs-bulk,Bulk API>>. As `_delete_by_query` uses scroll search, you can also specify
|
||||
the `scroll` parameter to control how long it keeps the "search context" alive,
|
||||
e.g. `?scroll=10m`. By default it's 5 minutes.
|
||||
shards to become available. Both work exactly the way they work in the
|
||||
<<docs-bulk,Bulk API>>. Delete by query uses scrolled searches, so you can also
|
||||
specify the `scroll` parameter to control how long it keeps the search context
|
||||
alive, for example `?scroll=10m`. The default is 5 minutes.
|
||||
|
||||
`requests_per_second` can be set to any positive decimal number (`1.4`, `6`,
|
||||
`1000`, etc.) and throttles the rate at which delete by query issues batches of
|
||||
delete operations by padding each batch with a wait time. The throttling can be
|
||||
disabled by setting `requests_per_second` to `-1`.
|
||||
===== Throttling delete requests
|
||||
|
||||
The throttling is done by waiting between batches so that scroll that
|
||||
`_delete_by_query` uses internally can be given a timeout that takes into
|
||||
account the padding. The padding time is the difference between the batch size
|
||||
divided by the `requests_per_second` and the time spent writing. By default the
|
||||
batch size is `1000`, so if the `requests_per_second` is set to `500`:
|
||||
To control the rate at which delete by query issues batches of delete operations,
|
||||
you can set `requests_per_second` to any positive decimal number. This pads each
|
||||
batch with a wait time to throttle the rate. Set `requests_per_second` to `-1`
|
||||
to disable throttling.
|
||||
|
||||
Throttling uses a wait time between batches so that the internal scroll requests
|
||||
can be given a timeout that takes the request padding into account. The padding
|
||||
time is the difference between the batch size divided by the
|
||||
`requests_per_second` and the time spent writing. By default the batch size is
|
||||
`1000`, so if `requests_per_second` is set to `500`:
|
||||
|
||||
[source,txt]
|
||||
--------------------------------------------------
|
||||
|
|
@ -182,11 +125,120 @@ target_time = 1000 / 500 per second = 2 seconds
|
|||
wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds
|
||||
--------------------------------------------------
|
||||
|
||||
Since the batch is issued as a single `_bulk` request, large batch sizes will
|
||||
cause Elasticsearch to create many requests and then wait for a while before
|
||||
starting the next set. This is "bursty" instead of "smooth". The default is `-1`.
|
||||
Since the batch is issued as a single `_bulk` request, large batch sizes
|
||||
cause {es} to create many requests and wait before starting the next set.
|
||||
This is "bursty" instead of "smooth".
|
||||
|
||||
[float]
|
||||
[[docs-delete-by-query-slice]]
|
||||
===== Slicing
|
||||
|
||||
Delete by query supports <<sliced-scroll, sliced scroll>> to parallelize the
|
||||
delete process. This can improve efficiency and provide a
|
||||
convenient way to break the request down into smaller parts.
|
||||
|
||||
Setting `slices` to `auto` chooses a reasonable number for most indices.
|
||||
If you're slicing manually or otherwise tuning automatic slicing, keep in mind
|
||||
that:
|
||||
|
||||
* Query performance is most efficient when the number of `slices` is equal to
|
||||
the number of shards in the index. If that number is large (for example,
|
||||
500), choose a lower number as too many `slices` hurts performance. Setting
|
||||
`slices` higher than the number of shards generally does not improve efficiency
|
||||
and adds overhead.
|
||||
|
||||
* Delete performance scales linearly across available resources with the
|
||||
number of slices.
|
||||
|
||||
Whether query or delete performance dominates the runtime depends on the
|
||||
documents being reindexed and cluster resources.
|
||||
|
||||
[[docs-delete-by-query-api-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`<index>`::
|
||||
(Optional, string) A comma-separated list of index names to search. Use `_all`
|
||||
or omit to search all indices.
|
||||
|
||||
[[docs-delete-by-query-api-query-params]]
|
||||
==== {api-query-parms-title}
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=analyzer]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=analyze_wildcard]
|
||||
|
||||
`conflicts`::
|
||||
(Optional, string) What to do if delete by query hits version conflicts:
|
||||
`abort` or `proceed`. Defaults to `abort`.
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=default_operator]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=df]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
|
||||
+
|
||||
Defaults to `open`.
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=from]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=lenient]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=max_docs]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=preference]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=search-q]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=request_cache]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=refresh]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=requests_per_second]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=routing]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=scroll]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=scroll_size]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=search_type]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=search_timeout]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=slices]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=sort]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=source]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=source_excludes]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=source_includes]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=stats]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=terminate_after]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeout]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=version]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeout]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]
|
||||
|
||||
[[docs-delete-by-query-api-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
||||
`query`::
|
||||
(Optional, <<query-dsl,query object>>) Specifies the documents to delete
|
||||
using the <<query-dsl,Query DSL>>.
|
||||
|
||||
|
||||
[[docs-delete-by-quer-api-response-body]]
|
||||
==== Response body
|
||||
|
||||
//////////////////////////
|
||||
|
|
@ -289,15 +341,260 @@ this is non-empty then the request aborted because of those failures.
|
|||
Delete by query is implemented using batches, and any failure causes the entire
|
||||
process to abort but all failures in the current batch are collected into the
|
||||
array. You can use the `conflicts` option to prevent reindex from aborting on
|
||||
version conflicts.
|
||||
version conflicts.
|
||||
|
||||
[[docs-delete-by-query-api-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
Delete all tweets from the `twitter` index:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST twitter/_delete_by_query?conflicts=proceed
|
||||
{
|
||||
"query": {
|
||||
"match_all": {}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[setup:twitter]
|
||||
|
||||
Delete documents from multiple indices:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST /twitter,blog/_delete_by_query
|
||||
{
|
||||
"query": {
|
||||
"match_all": {}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[s/^/PUT twitter\nPUT blog\n/]
|
||||
|
||||
Limit the delete by query operation to shards that a particular routing
|
||||
value:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST twitter/_delete_by_query?routing=1
|
||||
{
|
||||
"query": {
|
||||
"range" : {
|
||||
"age" : {
|
||||
"gte" : 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[setup:twitter]
|
||||
|
||||
By default `_delete_by_query` uses scroll batches of 1000. You can change the
|
||||
batch size with the `scroll_size` URL parameter:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST twitter/_delete_by_query?scroll_size=5000
|
||||
{
|
||||
"query": {
|
||||
"term": {
|
||||
"user": "kimchy"
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[setup:twitter]
|
||||
|
||||
[float]
|
||||
[[docs-delete-by-query-task-api]]
|
||||
==== Works with the Task API
|
||||
[[docs-delete-by-query-manual-slice]]
|
||||
===== Slice manually
|
||||
|
||||
Slice a delete by query manually by providing a slice id and total number of
|
||||
slices:
|
||||
|
||||
[source,js]
|
||||
----------------------------------------------------------------
|
||||
POST twitter/_delete_by_query
|
||||
{
|
||||
"slice": {
|
||||
"id": 0,
|
||||
"max": 2
|
||||
},
|
||||
"query": {
|
||||
"range": {
|
||||
"likes": {
|
||||
"lt": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
POST twitter/_delete_by_query
|
||||
{
|
||||
"slice": {
|
||||
"id": 1,
|
||||
"max": 2
|
||||
},
|
||||
"query": {
|
||||
"range": {
|
||||
"likes": {
|
||||
"lt": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
----------------------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[setup:big_twitter]
|
||||
|
||||
Which you can verify works with:
|
||||
|
||||
[source,js]
|
||||
----------------------------------------------------------------
|
||||
GET _refresh
|
||||
POST twitter/_search?size=0&filter_path=hits.total
|
||||
{
|
||||
"query": {
|
||||
"range": {
|
||||
"likes": {
|
||||
"lt": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
----------------------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
Which results in a sensible `total` like this one:
|
||||
|
||||
[source,js]
|
||||
----------------------------------------------------------------
|
||||
{
|
||||
"hits": {
|
||||
"total" : {
|
||||
"value": 0,
|
||||
"relation": "eq"
|
||||
}
|
||||
}
|
||||
}
|
||||
----------------------------------------------------------------
|
||||
// TESTRESPONSE
|
||||
|
||||
[float]
|
||||
[[docs-delete-by-query-automatic-slice]]
|
||||
===== Use automatic slicing
|
||||
|
||||
You can also let delete-by-query automatically parallelize using
|
||||
<<sliced-scroll, sliced scroll>> to slice on `_id`. Use `slices` to specify
|
||||
the number of slices to use:
|
||||
|
||||
[source,js]
|
||||
----------------------------------------------------------------
|
||||
POST twitter/_delete_by_query?refresh&slices=5
|
||||
{
|
||||
"query": {
|
||||
"range": {
|
||||
"likes": {
|
||||
"lt": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
----------------------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[setup:big_twitter]
|
||||
|
||||
Which you also can verify works with:
|
||||
|
||||
[source,js]
|
||||
----------------------------------------------------------------
|
||||
POST twitter/_search?size=0&filter_path=hits.total
|
||||
{
|
||||
"query": {
|
||||
"range": {
|
||||
"likes": {
|
||||
"lt": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
----------------------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
Which results in a sensible `total` like this one:
|
||||
|
||||
[source,js]
|
||||
----------------------------------------------------------------
|
||||
{
|
||||
"hits": {
|
||||
"total" : {
|
||||
"value": 0,
|
||||
"relation": "eq"
|
||||
}
|
||||
}
|
||||
}
|
||||
----------------------------------------------------------------
|
||||
// TESTRESPONSE
|
||||
|
||||
Setting `slices` to `auto` will let {es} choose the number of slices
|
||||
to use. This setting will use one slice per shard, up to a certain limit. If
|
||||
there are multiple source indices, it will choose the number of slices based
|
||||
on the index with the smallest number of shards.
|
||||
|
||||
Adding `slices` to `_delete_by_query` just automates the manual process used in
|
||||
the section above, creating sub-requests which means it has some quirks:
|
||||
|
||||
* You can see these requests in the
|
||||
<<docs-delete-by-query-task-api,Tasks APIs>>. These sub-requests are "child"
|
||||
tasks of the task for the request with `slices`.
|
||||
* Fetching the status of the task for the request with `slices` only contains
|
||||
the status of completed slices.
|
||||
* These sub-requests are individually addressable for things like cancellation
|
||||
and rethrottling.
|
||||
* Rethrottling the request with `slices` will rethrottle the unfinished
|
||||
sub-request proportionally.
|
||||
* Canceling the request with `slices` will cancel each sub-request.
|
||||
* Due to the nature of `slices` each sub-request won't get a perfectly even
|
||||
portion of the documents. All documents will be addressed, but some slices may
|
||||
be larger than others. Expect larger slices to have a more even distribution.
|
||||
* Parameters like `requests_per_second` and `max_docs` on a request with
|
||||
slices` are distributed proportionally to each sub-request. Combine that with
|
||||
the point above about distribution being uneven and you should conclude that
|
||||
using `max_docs` with `slices` might not result in exactly `max_docs` documents
|
||||
being deleted.
|
||||
* Each sub-request gets a slightly different snapshot of the source index
|
||||
though these are all taken at approximately the same time.
|
||||
|
||||
[float]
|
||||
[[docs-delete-by-query-rethrottle]]
|
||||
===== Change throttling for a request
|
||||
|
||||
The value of `requests_per_second` can be changed on a running delete by query
|
||||
using the `_rethrottle` API. Rethrottling that speeds up the
|
||||
query takes effect immediately but rethrotting that slows down the query
|
||||
takes effect after completing the current batch to prevent scroll
|
||||
timeouts.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST _delete_by_query/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
Use the <<tasks,tasks API>> to get the task ID. Set `requests_per_second`
|
||||
to any positive decimal value or `-1` to disable throttling.
|
||||
|
||||
===== Get the status of a delete by query operation
|
||||
|
||||
Use the <<tasks,tasks API>> to get the status of a delete by query
|
||||
operation:
|
||||
|
||||
You can fetch the status of any running delete by query requests with the
|
||||
<<tasks,Task API>>:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -371,7 +668,7 @@ you to delete that document.
|
|||
|
||||
[float]
|
||||
[[docs-delete-by-query-cancel-task-api]]
|
||||
==== Works with the Cancel Task API
|
||||
==== Cancel a delete by query operation
|
||||
|
||||
Any delete by query can be canceled using the <<tasks,task cancel API>>:
|
||||
|
||||
|
|
@ -386,215 +683,3 @@ The task ID can be found using the <<tasks,tasks API>>.
|
|||
Cancellation should happen quickly but might take a few seconds. The task status
|
||||
API above will continue to list the delete by query task until this task checks that it
|
||||
has been cancelled and terminates itself.
|
||||
|
||||
|
||||
[float]
|
||||
[[docs-delete-by-query-rethrottle]]
|
||||
==== Rethrottling
|
||||
|
||||
The value of `requests_per_second` can be changed on a running delete by query
|
||||
using the `_rethrottle` API:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST _delete_by_query/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
The task ID can be found using the <<tasks,tasks API>>.
|
||||
|
||||
Just like when setting it on the delete by query API, `requests_per_second`
|
||||
can be either `-1` to disable throttling or any decimal number
|
||||
like `1.7` or `12` to throttle to that level. Rethrottling that speeds up the
|
||||
query takes effect immediately but rethrotting that slows down the query will
|
||||
take effect after completing the current batch. This prevents scroll
|
||||
timeouts.
|
||||
|
||||
[float]
|
||||
[[docs-delete-by-query-slice]]
|
||||
==== Slicing
|
||||
|
||||
Delete by query supports <<sliced-scroll, sliced scroll>> to parallelize the deleting process.
|
||||
This parallelization can improve efficiency and provide a convenient way to
|
||||
break the request down into smaller parts.
|
||||
|
||||
[float]
|
||||
[[docs-delete-by-query-manual-slice]]
|
||||
===== Manual slicing
|
||||
|
||||
Slice a delete by query manually by providing a slice id and total number of
|
||||
slices to each request:
|
||||
|
||||
[source,js]
|
||||
----------------------------------------------------------------
|
||||
POST twitter/_delete_by_query
|
||||
{
|
||||
"slice": {
|
||||
"id": 0,
|
||||
"max": 2
|
||||
},
|
||||
"query": {
|
||||
"range": {
|
||||
"likes": {
|
||||
"lt": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
POST twitter/_delete_by_query
|
||||
{
|
||||
"slice": {
|
||||
"id": 1,
|
||||
"max": 2
|
||||
},
|
||||
"query": {
|
||||
"range": {
|
||||
"likes": {
|
||||
"lt": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
----------------------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[setup:big_twitter]
|
||||
|
||||
Which you can verify works with:
|
||||
|
||||
[source,js]
|
||||
----------------------------------------------------------------
|
||||
GET _refresh
|
||||
POST twitter/_search?size=0&filter_path=hits.total
|
||||
{
|
||||
"query": {
|
||||
"range": {
|
||||
"likes": {
|
||||
"lt": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
----------------------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
Which results in a sensible `total` like this one:
|
||||
|
||||
[source,js]
|
||||
----------------------------------------------------------------
|
||||
{
|
||||
"hits": {
|
||||
"total" : {
|
||||
"value": 0,
|
||||
"relation": "eq"
|
||||
}
|
||||
}
|
||||
}
|
||||
----------------------------------------------------------------
|
||||
// TESTRESPONSE
|
||||
|
||||
[float]
|
||||
[[docs-delete-by-query-automatic-slice]]
|
||||
===== Automatic slicing
|
||||
|
||||
You can also let delete-by-query automatically parallelize using
|
||||
<<sliced-scroll, sliced scroll>> to slice on `_id`. Use `slices` to specify the number of
|
||||
slices to use:
|
||||
|
||||
[source,js]
|
||||
----------------------------------------------------------------
|
||||
POST twitter/_delete_by_query?refresh&slices=5
|
||||
{
|
||||
"query": {
|
||||
"range": {
|
||||
"likes": {
|
||||
"lt": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
----------------------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[setup:big_twitter]
|
||||
|
||||
Which you also can verify works with:
|
||||
|
||||
[source,js]
|
||||
----------------------------------------------------------------
|
||||
POST twitter/_search?size=0&filter_path=hits.total
|
||||
{
|
||||
"query": {
|
||||
"range": {
|
||||
"likes": {
|
||||
"lt": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
----------------------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
Which results in a sensible `total` like this one:
|
||||
|
||||
[source,js]
|
||||
----------------------------------------------------------------
|
||||
{
|
||||
"hits": {
|
||||
"total" : {
|
||||
"value": 0,
|
||||
"relation": "eq"
|
||||
}
|
||||
}
|
||||
}
|
||||
----------------------------------------------------------------
|
||||
// TESTRESPONSE
|
||||
|
||||
Setting `slices` to `auto` will let Elasticsearch choose the number of slices
|
||||
to use. This setting will use one slice per shard, up to a certain limit. If
|
||||
there are multiple source indices, it will choose the number of slices based
|
||||
on the index with the smallest number of shards.
|
||||
|
||||
Adding `slices` to `_delete_by_query` just automates the manual process used in
|
||||
the section above, creating sub-requests which means it has some quirks:
|
||||
|
||||
* You can see these requests in the
|
||||
<<docs-delete-by-query-task-api,Tasks APIs>>. These sub-requests are "child"
|
||||
tasks of the task for the request with `slices`.
|
||||
* Fetching the status of the task for the request with `slices` only contains
|
||||
the status of completed slices.
|
||||
* These sub-requests are individually addressable for things like cancellation
|
||||
and rethrottling.
|
||||
* Rethrottling the request with `slices` will rethrottle the unfinished
|
||||
sub-request proportionally.
|
||||
* Canceling the request with `slices` will cancel each sub-request.
|
||||
* Due to the nature of `slices` each sub-request won't get a perfectly even
|
||||
portion of the documents. All documents will be addressed, but some slices may
|
||||
be larger than others. Expect larger slices to have a more even distribution.
|
||||
* Parameters like `requests_per_second` and `max_docs` on a request with
|
||||
slices` are distributed proportionally to each sub-request. Combine that with
|
||||
the point above about distribution being uneven and you should conclude that
|
||||
using `max_docs` with `slices` might not result in exactly `max_docs` documents
|
||||
being deleted.
|
||||
* Each sub-request gets a slightly different snapshot of the source index
|
||||
though these are all taken at approximately the same time.
|
||||
|
||||
[float]
|
||||
[[docs-delete-by-query-picking-slices]]
|
||||
====== Picking the number of slices
|
||||
|
||||
If slicing automatically, setting `slices` to `auto` will choose a reasonable
|
||||
number for most indices. If you're slicing manually or otherwise tuning
|
||||
automatic slicing, use these guidelines.
|
||||
|
||||
Query performance is most efficient when the number of `slices` is equal to the
|
||||
number of shards in the index. If that number is large (for example,
|
||||
500), choose a lower number as too many `slices` will hurt performance. Setting
|
||||
`slices` higher than the number of shards generally does not improve efficiency
|
||||
and adds overhead.
|
||||
|
||||
Delete performance scales linearly across available resources with the
|
||||
number of slices.
|
||||
|
||||
Whether query or delete performance dominates the runtime depends on the
|
||||
documents being reindexed and cluster resources.
|
||||
|
|
|
|||
|
|
@ -144,23 +144,23 @@ DELETE /twitter/_doc/1?timeout=5m
|
|||
[[docs-delete-api-query-params]]
|
||||
==== {api-query-parms-title}
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-seq-no]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=if_seq_no]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-primary-term]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=if_primary_term]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-pipeline]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=pipeline]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-refresh]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=refresh]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-routing]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=routing]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeout]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-version]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-version-type]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=version_type]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-wait-for-active-shards]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]
|
||||
|
||||
[[docs-delete-api-example]]
|
||||
==== {api-examples-title}
|
||||
|
|
|
|||
|
|
@ -164,9 +164,9 @@ be performed on (default: random).
|
|||
(Optional, boolean) Set to `false` to disable real time GET
|
||||
(default: `true`). See <<realtime>>.
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-refresh]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=refresh]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-routing]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=routing]
|
||||
|
||||
`stored_fields`::
|
||||
(Optional, boolean) Set to `true` to retrieve the document fields stored in the
|
||||
|
|
@ -185,7 +185,7 @@ you want to retrieve.
|
|||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-version]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-version-type]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=version_type]
|
||||
|
||||
[[docs-get-api-response-body]]
|
||||
==== {api-response-body-title}
|
||||
|
|
|
|||
|
|
@ -37,9 +37,9 @@ POST request.
|
|||
[[docs-index-api-query-params]]
|
||||
==== {api-query-parms-title}
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-seq-no]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=if_seq_no]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-primary-term]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=if_primary_term]
|
||||
|
||||
`op_type`::
|
||||
(Optional, enum) Set to `create` to only index the document
|
||||
|
|
@ -47,19 +47,19 @@ if it does not already exist (_put if absent_). If a document with the specified
|
|||
`_id` already exists, the indexing operation will fail. Same as using the
|
||||
`<index>/_create` endpoint. Valid values: `index`, `create`. Default: `index`.
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-pipeline]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=pipeline]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-refresh]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=refresh]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-routing]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=routing]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-version]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-version-type]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=version_type]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-wait-for-active-shards]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]
|
||||
|
||||
[[docs-index-api-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
|
|
|||
|
|
@ -46,22 +46,20 @@ automatically if it doesn't exist. For more information, see <<index-creation>>.
|
|||
[[docs-update-api-query-params]]
|
||||
==== {api-query-parms-title}
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-seq-no]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=if_seq_no]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-primary-term]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=if_primary_term]
|
||||
|
||||
`lang`::
|
||||
(Optional, string) The script language. Default: `painless`.
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-refresh]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=refresh]
|
||||
|
||||
`retry_on_conflict`::
|
||||
(Optional, integer) Specify how many times should the operation be retried when
|
||||
a conflict occurs. Default: 0.
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-refresh]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-routing]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=routing]
|
||||
|
||||
`_source`::
|
||||
(Optional, list) Set to `false` to disable source retrieval (default: `true`).
|
||||
|
|
@ -75,7 +73,7 @@ You can also specify a comma-separated list of the fields you want to retrieve.
|
|||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-wait-for-active-shards]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]
|
||||
|
||||
[[update-api-example]]
|
||||
==== {api-examples-title}
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@ Defaults to `open`.
|
|||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-wait-for-active-shards]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
|
||||
|
||||
|
|
|
|||
|
|
@ -52,7 +52,7 @@ Index names must meet the following criteria:
|
|||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=include-type-name]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-wait-for-active-shards]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
|
||||
|
||||
|
|
|
|||
|
|
@ -88,7 +88,7 @@ Defaults to `closed`.
|
|||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-wait-for-active-shards]
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
|
||||
|
||||
|
|
|
|||
|
|
@ -4,6 +4,14 @@ Comma-separated list or wildcard expression of index alias names
|
|||
used to limit the request.
|
||||
end::index-alias[]
|
||||
|
||||
tag::index-alias-filter[]
|
||||
<<query-dsl-bool-query, Filter query>>
|
||||
used to limit the index alias.
|
||||
+
|
||||
If specified,
|
||||
the index alias only applies to documents returned by the filter.
|
||||
end::index-alias-filter[]
|
||||
|
||||
tag::allow-no-indices[]
|
||||
`allow_no_indices`::
|
||||
(Optional, boolean) If `true`, the request returns an error if a wildcard
|
||||
|
|
@ -12,11 +20,34 @@ parameter also applies to <<indices-aliases,index aliases>> that point to a
|
|||
missing or closed index.
|
||||
end::allow-no-indices[]
|
||||
|
||||
tag::analyzer[]
|
||||
analyzer`::
|
||||
(Optional, string) Analyzer to use for the query string.
|
||||
end::analyzer[]
|
||||
|
||||
tag::analyze_wildcard[]
|
||||
`analyze_wildcard`::
|
||||
(Optional, boolean) If `true`, wildcard and prefix queries are
|
||||
analyzed. Defaults to `false`.
|
||||
end::analyze_wildcard[]
|
||||
|
||||
tag::bytes[]
|
||||
`bytes`::
|
||||
(Optional, <<byte-units,byte size units>>) Unit used to display byte values.
|
||||
end::bytes[]
|
||||
|
||||
tag::default_operator[]
|
||||
`default_operator`::
|
||||
(Optional, string) The default operator for query string query: AND or OR.
|
||||
Defaults to `OR`.
|
||||
end::default_operator[]
|
||||
|
||||
tag::df[]
|
||||
`df`::
|
||||
(Optional, string) Field to use as default where no field prefix is
|
||||
given in the query string.
|
||||
end::df[]
|
||||
|
||||
tag::expand-wildcards[]
|
||||
`expand_wildcards`::
|
||||
+
|
||||
|
|
@ -44,14 +75,6 @@ tag::flat-settings[]
|
|||
`false`.
|
||||
end::flat-settings[]
|
||||
|
||||
tag::index-alias-filter[]
|
||||
<<query-dsl-bool-query, Filter query>>
|
||||
used to limit the index alias.
|
||||
+
|
||||
If specified,
|
||||
the index alias only applies to documents returned by the filter.
|
||||
end::index-alias-filter[]
|
||||
|
||||
tag::http-format[]
|
||||
`format`::
|
||||
(Optional, string) Short version of the
|
||||
|
|
@ -59,6 +82,34 @@ https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html[HTTP accept header].
|
|||
Valid values include JSON, YAML, etc.
|
||||
end::http-format[]
|
||||
|
||||
tag::from[]
|
||||
`from`::
|
||||
(Optional, integer) Starting document offset. Defaults to `0`.
|
||||
end::from[]
|
||||
|
||||
tag::cat-h[]
|
||||
`h`::
|
||||
(Optional, string) Comma-separated list of column names to display.
|
||||
end::cat-h[]
|
||||
|
||||
tag::help[]
|
||||
`help`::
|
||||
(Optional, boolean) If `true`, the response returns help information. Defaults
|
||||
to `false`.
|
||||
end::help[]
|
||||
|
||||
tag::if_primary_term[]
|
||||
`if_primary_term`::
|
||||
(Optional, integer) Only perform the operation if the document has
|
||||
this primary term. See <<optimistic-concurrency-control-index>>.
|
||||
end::if_primary_term[]
|
||||
|
||||
tag::if_seq_no[]
|
||||
`if_seq_no`::
|
||||
(Optional, integer) Only perform the operation if the document has this
|
||||
sequence number. See <<optimistic-concurrency-control-index>>.
|
||||
end::if_seq_no[]
|
||||
|
||||
tag::cat-h[]
|
||||
`h`::
|
||||
(Optional, string) Comma-separated list of column names to display.
|
||||
|
|
@ -101,6 +152,12 @@ tag::index[]
|
|||
used to limit the request.
|
||||
end::index[]
|
||||
|
||||
tag::lenient[]
|
||||
`lenient`::
|
||||
(Optional, boolean) If `true`, format-based query failures (such as
|
||||
providing text to a numeric field) will be ignored. Defaults to `false`.
|
||||
end::lenient[]
|
||||
|
||||
tag::local[]
|
||||
`local`::
|
||||
(Optional, boolean) If `true`, the request retrieves information from the local
|
||||
|
|
@ -108,6 +165,12 @@ node only. Defaults to `false`, which means information is retrieved from
|
|||
the master node.
|
||||
end::local[]
|
||||
|
||||
tag::max_docs[]
|
||||
`max_docs`::
|
||||
(Optional, integer) Maximum number of documents to process. Defaults to all
|
||||
documents.
|
||||
end::max_docs[]
|
||||
|
||||
tag::name[]
|
||||
`<name>`::
|
||||
(Optional, string) Comma-separated list of alias names to return.
|
||||
|
|
@ -119,47 +182,46 @@ tag::node-id[]
|
|||
returned information.
|
||||
end::node-id[]
|
||||
|
||||
tag::cat-s[]
|
||||
`s`::
|
||||
(Optional, string) Comma-separated list of column names or column aliases used
|
||||
to sort the response.
|
||||
end::cat-s[]
|
||||
|
||||
tag::cat-v[]
|
||||
`v`::
|
||||
(Optional, boolean) If `true`, the response includes column headings. Defaults
|
||||
to `false`.
|
||||
end::cat-v[]
|
||||
|
||||
tag::doc-pipeline[]
|
||||
tag::pipeline[]
|
||||
`pipeline`::
|
||||
(Optional, string) ID of the pipeline to use to preprocess incoming documents.
|
||||
end::doc-pipeline[]
|
||||
end::pipeline[]
|
||||
|
||||
tag::doc-refresh[]
|
||||
tag::preference[]
|
||||
`preference`::
|
||||
(Optional, string) Specifies the node or shard the operation should be
|
||||
performed on. Random by default.
|
||||
end::preference[]
|
||||
|
||||
tag::search-q[]
|
||||
`q`::
|
||||
(Optional, string) Query in the Lucene query string syntax.
|
||||
end::search-q[]
|
||||
|
||||
tag::refresh[]
|
||||
`refresh`::
|
||||
(Optional, enum) If `true`, {es} refreshes the affected shards to make this
|
||||
operation visible to search, if `wait_for` then wait for a refresh to make
|
||||
this operation visible to search, if `false` do nothing with refreshes.
|
||||
Valid values: `true`, `false`, `wait_for`. Default: `false`.
|
||||
end::doc-refresh[]
|
||||
end::refresh[]
|
||||
|
||||
tag::doc-seq-no[]
|
||||
`if_seq_no`::
|
||||
(Optional, integer) Only perform the operation if the document has this
|
||||
sequence number. See <<optimistic-concurrency-control-index>>.
|
||||
end::doc-seq-no[]
|
||||
tag::request_cache[]
|
||||
`request_cache`::
|
||||
(Optional, boolean) Specifies if the request cache should be used for this
|
||||
request. Defaults to the index-level setting.
|
||||
end::request_cache[]
|
||||
|
||||
tag::doc-primary-term[]
|
||||
`if_primary_term`::
|
||||
(Optional, integer) Only perform the operation if the document has
|
||||
this primary term. See <<optimistic-concurrency-control-index>>.
|
||||
end::doc-primary-term[]
|
||||
tag::requests_per_second[]
|
||||
`requests_per_second`::
|
||||
(Optional, integer) The throttle for this request in sub-requests per second.
|
||||
-1 means no throttle. Defaults to 0.
|
||||
end::requests_per_second[]
|
||||
|
||||
tag::doc-routing[]
|
||||
tag::routing[]
|
||||
`routing`::
|
||||
(Optional, string) Target the specified primary shard.
|
||||
end::doc-routing[]
|
||||
end::routing[]
|
||||
|
||||
tag::index-routing[]
|
||||
`routing`::
|
||||
|
|
@ -168,31 +230,77 @@ Custom <<mapping-routing-field, routing value>>
|
|||
used to route operations to a specific shard.
|
||||
end::index-routing[]
|
||||
|
||||
tag::doc-version[]
|
||||
`version`::
|
||||
(Optional, integer) Explicit version number for concurrency control.
|
||||
The specified version must match the current version of the document for the
|
||||
request to succeed.
|
||||
end::doc-version[]
|
||||
tag::cat-s[]
|
||||
`s`::
|
||||
(Optional, string) Comma-separated list of column names or column aliases used
|
||||
to sort the response.
|
||||
end::cat-s[]
|
||||
|
||||
tag::doc-version-type[]
|
||||
`version_type`::
|
||||
(Optional, enum) Specific version type: `internal`, `external`,
|
||||
`external_gte`, `force`.
|
||||
end::doc-version-type[]
|
||||
tag::scroll[]
|
||||
`scroll`::
|
||||
(Optional, <<time-units, time units>>) Specifies how long a consistent view of
|
||||
the index should be maintained for scrolled search.
|
||||
end::scroll[]
|
||||
|
||||
tag::doc-wait-for-active-shards[]
|
||||
`wait_for_active_shards`::
|
||||
+
|
||||
--
|
||||
(Optional, 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`).
|
||||
Default: 1, the primary shard.
|
||||
tag::scroll_size[]
|
||||
`scroll_size`::
|
||||
(Optional, integer) Size of the scroll request that powers the operation.
|
||||
Defaults to 100.
|
||||
end::scroll_size[]
|
||||
|
||||
See <<index-wait-for-active-shards>>.
|
||||
--
|
||||
end::doc-wait-for-active-shards[]
|
||||
tag::search_timeout[]
|
||||
`search_timeout`::
|
||||
(Optional, <<time-units, time units>> Explicit timeout for each search
|
||||
request. Defaults to no timeout.
|
||||
end::search_timeout[]
|
||||
|
||||
tag::search_type[]
|
||||
`search_type`::
|
||||
(Optional, string) The type of the search operation. Available options:
|
||||
* `query_then_fetch`
|
||||
* `dfs_query_then_fetch`
|
||||
end::search_type[]
|
||||
|
||||
tag::slices[]
|
||||
`slices`::
|
||||
(Optional, integer) The number of slices this task should be divided into.
|
||||
Defaults to 1 meaning the task isn't sliced into subtasks.
|
||||
end::slices[]
|
||||
|
||||
tag::sort[]
|
||||
`sort`::
|
||||
(Optional, string) A comma-separated list of <field>:<direction> pairs.
|
||||
end::sort[]
|
||||
|
||||
tag::source[]
|
||||
`_source`::
|
||||
(Optional, string) True or false to return the `_source` field or not, or a
|
||||
list of fields to return.
|
||||
end::source[]
|
||||
|
||||
tag::source_excludes[]
|
||||
`_source_excludes`::
|
||||
(Optional, string) A list of fields to exclude from the returned `_source`
|
||||
field.
|
||||
end::source_excludes[]
|
||||
|
||||
tag::source_includes[]
|
||||
`_source_includes`::
|
||||
(Optional, string) A list of fields to extract and return from the `_source`
|
||||
field.
|
||||
end::source_includes[]
|
||||
|
||||
tag::stats[]
|
||||
`stats`::
|
||||
(Optional, string) Specific `tag` of the request for logging and statistical
|
||||
purposes.
|
||||
end::stats[]
|
||||
|
||||
tag::terminate_after[]
|
||||
`terminate_after`::
|
||||
(Optional, integer) The maximum number of documents to collect for each shard,
|
||||
upon reaching which the query execution will terminate early.
|
||||
end::terminate_after[]
|
||||
|
||||
tag::timeoutparms[]
|
||||
|
||||
|
|
@ -211,3 +319,46 @@ expires, the request fails and returns an error. Defaults to `30s`.
|
|||
end::master-timeout[]
|
||||
|
||||
end::timeoutparms[]
|
||||
|
||||
tag::cat-v[]
|
||||
`v`::
|
||||
(Optional, boolean) If `true`, the response includes column headings. Defaults
|
||||
to `false`.
|
||||
end::cat-v[]
|
||||
|
||||
tag::version[]
|
||||
`version`::
|
||||
(Optional, boolean) If `true`, returns the document version as part of a hit.
|
||||
end::version[]
|
||||
|
||||
tag::doc-version[]
|
||||
`version`::
|
||||
(Optional, integer) Explicit version number for concurrency control.
|
||||
The specified version must match the current version of the document for the
|
||||
request to succeed.
|
||||
end::doc-version[]
|
||||
|
||||
tag::version_type[]
|
||||
`version_type`::
|
||||
(Optional, enum) Specific version type: `internal`, `external`,
|
||||
`external_gte`, `force`.
|
||||
end::version_type[]
|
||||
|
||||
tag::wait_for_active_shards[]
|
||||
`wait_for_active_shards`::
|
||||
+
|
||||
--
|
||||
(Optional, 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`).
|
||||
Default: 1, the primary shard.
|
||||
|
||||
See <<index-wait-for-active-shards>>.
|
||||
--
|
||||
end::wait_for_active_shards[]
|
||||
|
||||
tag::wait_for_completion[]
|
||||
`wait_for_completion`::
|
||||
(Optional, boolean) Should the request block until the operation is
|
||||
complete. Defaults to `true`.
|
||||
end::wait_for_completion[]
|
||||
|
|
|
|||
Loading…
Reference in New Issue