mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-06 21:18:31 +00:00
a63f60b776
Several files in the REST APIs nav section are included using :leveloffset: tags. This increments headings (h2 -> h3, h3 -> h4, etc.) in those files and removes the :leveloffset: tags. Other supporting changes: * Alphabetizes top-level REST API nav items. * Change 'indices APIs' heading to 'index APIs.' * Changes 'Snapshot lifecycle management' heading to sentence case.
152 lines
4.7 KiB
Plaintext
152 lines
4.7 KiB
Plaintext
[[docs-delete]]
|
|
=== Delete API
|
|
|
|
The delete API allows to delete a JSON document from a specific
|
|
index based on its id. The following example deletes the JSON document
|
|
from an index called `twitter` with ID `1`:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
DELETE /twitter/_doc/1
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[setup:twitter]
|
|
|
|
The result of the above delete operation is:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"_shards" : {
|
|
"total" : 2,
|
|
"failed" : 0,
|
|
"successful" : 2
|
|
},
|
|
"_index" : "twitter",
|
|
"_type" : "_doc",
|
|
"_id" : "1",
|
|
"_version" : 2,
|
|
"_primary_term": 1,
|
|
"_seq_no": 5,
|
|
"result": "deleted"
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/"successful" : 2/"successful" : 1/]
|
|
// TESTRESPONSE[s/"_primary_term" : 1/"_primary_term" : $body._primary_term/]
|
|
// TESTRESPONSE[s/"_seq_no" : 5/"_seq_no" : $body._seq_no/]
|
|
|
|
[float]
|
|
[[optimistic-concurrency-control-delete]]
|
|
==== Optimistic concurrency control
|
|
|
|
Delete operations can be made conditional and only be performed if the last
|
|
modification to the document was assigned the sequence number and primary
|
|
term specified by the `if_seq_no` and `if_primary_term` parameters. If a
|
|
mismatch is detected, the operation will result in a `VersionConflictException`
|
|
and a status code of 409. See <<optimistic-concurrency-control>> for more details.
|
|
|
|
[float]
|
|
[[delete-versioning]]
|
|
==== Versioning
|
|
|
|
Each document indexed is versioned. When deleting a document, the `version` can
|
|
be specified to make sure the relevant document we are trying to delete is
|
|
actually being deleted and it has not changed in the meantime. Every write
|
|
operation executed on a document, deletes included, causes its version to be
|
|
incremented. The version number of a deleted document remains available for a
|
|
short time after deletion to allow for control of concurrent operations. The
|
|
length of time for which a deleted document's version remains available is
|
|
determined by the `index.gc_deletes` index setting and defaults to 60 seconds.
|
|
|
|
[float]
|
|
[[delete-routing]]
|
|
==== Routing
|
|
|
|
When indexing using the ability to control the routing, in order to
|
|
delete a document, the routing value should also be provided. For
|
|
example:
|
|
|
|
////
|
|
Example to delete with routing
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT /twitter/_doc/1?routing=kimchy
|
|
{
|
|
"test": "test"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
////
|
|
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
DELETE /twitter/_doc/1?routing=kimchy
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
The above will delete a tweet with id `1`, but will be routed based on the
|
|
user. Note that issuing a delete without the correct routing will cause the
|
|
document to not be deleted.
|
|
|
|
When the `_routing` mapping is set as `required` and no routing value is
|
|
specified, the delete API will throw a `RoutingMissingException` and reject
|
|
the request.
|
|
|
|
[float]
|
|
[[delete-index-creation]]
|
|
==== Automatic index creation
|
|
|
|
If an <<docs-index_,external versioning variant>> is used,
|
|
the delete operation automatically creates an index if it has not been
|
|
created before (check out the <<indices-create-index,create index API>>
|
|
for manually creating an index).
|
|
|
|
[float]
|
|
[[delete-distributed]]
|
|
==== Distributed
|
|
|
|
The delete operation gets hashed into a specific shard id. It then gets
|
|
redirected into the primary shard within that id group, and replicated
|
|
(if needed) to shard replicas within that id group.
|
|
|
|
[float]
|
|
[[delete-wait-for-active-shards]]
|
|
==== Wait For Active Shards
|
|
|
|
When making delete requests, you can set the `wait_for_active_shards`
|
|
parameter to require a minimum number of shard copies to be active
|
|
before starting to process the delete request. See
|
|
<<index-wait-for-active-shards,here>> for further details and a usage
|
|
example.
|
|
|
|
[float]
|
|
[[delete-refresh]]
|
|
==== Refresh
|
|
|
|
Control when the changes made by this request are visible to search. See
|
|
<<docs-refresh>>.
|
|
|
|
|
|
[float]
|
|
[[delete-timeout]]
|
|
==== Timeout
|
|
|
|
The primary shard assigned to perform the delete operation might not be
|
|
available when the delete operation is executed. Some reasons for this
|
|
might be that the primary shard is currently recovering from a store
|
|
or undergoing relocation. By default, the delete operation will wait on
|
|
the primary shard to become available for up to 1 minute before failing
|
|
and responding with an error. The `timeout` parameter can be used to
|
|
explicitly specify how long it waits. Here is an example of setting it
|
|
to 5 minutes:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
DELETE /twitter/_doc/1?timeout=5m
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[setup:twitter]
|