elasticsearch/docs/reference/docs/delete.asciidoc

[[docs-delete]]
== Delete API

The 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:

[source,js]
--------------------------------------------------
$ curl -XDELETE 'http://localhost:9200/twitter/tweet/1'
--------------------------------------------------

The result of the above delete operation is:

[source,js]
--------------------------------------------------
{
    "_shards" : {
        "total" : 10,
        "failed" : 0,
        "successful" : 10
    },
    "found" : true,
    "_index" : "twitter",
    "_type" : "tweet",
    "_id" : "1",
    "_version" : 2,
    "result": "deleted"
}
--------------------------------------------------

[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.

[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:

[source,js]
--------------------------------------------------
$ 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.

[float]
[[delete-parent]]
=== Parent

The `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 <<docs-delete-by-query,Delete By Query API>> to perform a
 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.

[float]
[[delete-index-creation]]
=== Automatic index creation

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), and also automatically creates a
dynamic type mapping for the specific type if it has not been created
before (check out the <<indices-put-mapping,put mapping>>
API for manually creating type mapping).

[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]
--------------------------------------------------
$ curl -XDELETE 'http://localhost:9200/twitter/tweet/1?timeout=5m'
--------------------------------------------------