195 lines
5.7 KiB
Plaintext
195 lines
5.7 KiB
Plaintext
[[docs-delete]]
|
|
=== Delete API
|
|
++++
|
|
<titleabbrev>Delete</titleabbrev>
|
|
++++
|
|
|
|
Removes a JSON document from the specified index.
|
|
|
|
[[docs-delete-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`DELETE /<index>/_doc/<_id>`
|
|
|
|
[[docs-delete-api-desc]]
|
|
==== {api-description-title}
|
|
|
|
You use DELETE to remove a document from an index. You must specify the
|
|
index name and document ID.
|
|
|
|
[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
|
|
|
|
If routing is used during indexing, the routing value also needs to be
|
|
specified to delete a document.
|
|
|
|
If the `_routing` mapping is set to `required` and no routing value is
|
|
specified, the delete API throws a `RoutingMissingException` and rejects
|
|
the request.
|
|
|
|
For example:
|
|
|
|
|
|
////
|
|
Example to delete with routing
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /twitter/_doc/1?routing=kimchy
|
|
{
|
|
"test": "test"
|
|
}
|
|
--------------------------------------------------
|
|
////
|
|
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
DELETE /twitter/_doc/1?routing=kimchy
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
This request deletes the tweet with id `1`, but it is routed based on the
|
|
user. The document is not deleted if the correct routing is not specified.
|
|
|
|
[float]
|
|
[[delete-index-creation]]
|
|
===== Automatic index creation
|
|
|
|
If an <<docs-index_,external versioning variant>> is used,
|
|
the delete operation automatically creates the specified index if it does not
|
|
exist. For information about manually creating indices, see
|
|
<<indices-create-index,create index API>>.
|
|
|
|
[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,console]
|
|
--------------------------------------------------
|
|
DELETE /twitter/_doc/1?timeout=5m
|
|
--------------------------------------------------
|
|
// TEST[setup:twitter]
|
|
|
|
[[docs-delete-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<index>`::
|
|
(Required, string) Name of the target index.
|
|
|
|
`<_id>`::
|
|
(Required, string) Unique identifier for the document.
|
|
|
|
[[docs-delete-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=if_seq_no]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=if_primary_term]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=pipeline]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=refresh]
|
|
|
|
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=version_type]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]
|
|
|
|
[[docs-delete-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
Delete the JSON document `1` from the `twitter` index:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
DELETE /twitter/_doc/1
|
|
--------------------------------------------------
|
|
// TEST[setup:twitter]
|
|
|
|
The API returns the following result:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"_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/]
|