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]
--------------------------------------------------
{
    "found" : true,
    "_index" : "twitter",
    "_type" : "tweet",
    "_id" : "1",
    "_version" : 2
}
--------------------------------------------------

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

Many times, the routing value is not known when deleting a document. For
those cases, when specifying the `_routing` mapping as `required`, and
no routing value is specified, the delete will be broadcasted
automatically to all shards.

[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 perform a <<docs-delete-by-query,delete by query>> on the child
index with the automatically generated (and indexed)
field _parent, which is in the format parent_type#parent_id.

[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-replication]]
=== Replication Type

The replication of the operation can be done in an asynchronous manner
to the replicas (the operation will return once it has be executed on
the primary shard). The `replication` parameter can be set to `async`
(defaults to `sync`) in order to enable it.

[float]
[[delete-consistency]]
=== Write Consistency

Control 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).

[float]
[[delete-refresh]]
=== Refresh

The `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).

[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 gateway
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'
--------------------------------------------------