Delete API
editDelete API
editThe delete API allows to delete a typed JSON document from a specific
index based on its id. The following example deletes the JSON document
from an index called twitter
, under a type called _doc
, with id 1
:
DELETE /twitter/_doc/1
The result of the above delete operation is:
{ "_shards" : { "total" : 2, "failed" : 0, "successful" : 2 }, "_index" : "twitter", "_type" : "_doc", "_id" : "1", "_version" : 2, "_primary_term": 1, "_seq_no": 5, "result": "deleted" }
Versioning
editEach 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.
Routing
editWhen indexing using the ability to control the routing, in order to delete a document, the routing value should also be provided. For example:
DELETE /twitter/_doc/1?routing=kimchy
The above will delete a tweet with id 1
, but will be routed based on the
user. Note, 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.
Automatic index creation
editIf an external versioning variant is used, the delete operation automatically creates an index if it has not been created before (check out the create index API for manually creating an index), and also automatically creates a dynamic type mapping for the specific type if it has not been created before (check out the put mapping API for manually creating type mapping).
Distributed
editThe 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.
Wait For Active Shards
editWhen 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
here for further details and a usage
example.
Refresh
editControl when the changes made by this request are visible to search. See
?refresh
.
Timeout
editThe 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:
DELETE /twitter/_doc/1?timeout=5m