WARNING: Version 2.3 of Elasticsearch has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
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 tweet, with id valued 1:
$ curl -XDELETE 'http://localhost:9200/twitter/tweet/1'
The result of the above delete operation is:
{ "_shards" : { "total" : 10, "failed" : 0, "successful" : 10 }, "found" : true, "_index" : "twitter", "_type" : "tweet", "_id" : "1", "_version" : 2 }
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.
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:
$ curl -XDELETE 'http://localhost:9200/twitter/tweet/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.
Parent
editThe parent
parameter can be set, which will basically be the same as
setting the routing parameter.
Note that deleting a parent document does not automatically delete its
children. One way of deleting all child documents given a parent’s id is
to use the delete-by-query
plugin to perform a delete on the child
index with the automatically generated (and indexed)
field _parent, which is in the format parent_type#parent_id.
When deleting a child document its parent id must be specified, otherwise
the delete request will be rejected and a RoutingMissingException
will be
thrown instead.
Automatic index creation
editThe 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.
Write Consistency
editControl if the operation will be allowed to execute based on the number
of active shards within that partition (replication group). The values
allowed are one
, quorum
, and all
. The parameter to set it is
consistency
, and it defaults to the node level setting of
action.write_consistency
which in turn defaults to quorum
.
For example, in a N shards with 2 replicas index, there will have to be
at least 2 active shards within the relevant partition (quorum
) for
the operation to succeed. In a N shards with 1 replica scenario, there
will need to be a single shard active (in this case, one
and quorum
is the same).
Refresh
editThe refresh
parameter can be set to true
in order to refresh the relevant
primary and replica shards after the delete operation has occurred and make it
searchable. Setting it to true
should be done after careful thought and
verification that this does not cause a heavy load on the system (and slows
down indexing).
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:
$ curl -XDELETE 'http://localhost:9200/twitter/tweet/1?timeout=5m'