elasticsearch/docs/reference/docs/delete.asciidoc

[[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-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `delete` or
`write` <<privileges-list-indices,index privilege>> for the target index or
index alias.

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

NOTE: You cannot send deletion requests directly to a data stream. To delete a
document in a data stream, you must target the backing index containing the
document. See <<update-delete-docs-in-a-backing-index>>.

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

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

[discrete]
[[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 /my-index-000001/_doc/1?routing=shard-1
{
  "test": "test"
}
--------------------------------------------------
////


[source,console]
--------------------------------------------------
DELETE /my-index-000001/_doc/1?routing=shard-1
--------------------------------------------------
// TEST[continued]

This request deletes the document with id `1`, but it is routed based on the
user. The document is not deleted if the correct routing is not specified.

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

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

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

[discrete]
[[delete-refresh]]
===== Refresh

Control when the changes made by this request are visible to search. See
<<docs-refresh>>.

[discrete]
[[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 /my-index-000001/_doc/1?timeout=5m
--------------------------------------------------
// TEST[setup:my_index]

[[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::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=if_seq_no]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=if_primary_term]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=refresh]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=routing]

`timeout`::
(Optional, <<time-units, time units>>)
Period to <<index-wait-for-active-shards,wait for active shards>>. Defaults to
`1m` (one minute).

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=doc-version]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=version_type]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]

[[docs-delete-api-example]]
==== {api-examples-title}

Delete the JSON document `1` from the `my-index-000001` index:

[source,console]
--------------------------------------------------
DELETE /my-index-000001/_doc/1
--------------------------------------------------
// TEST[setup:my_index]

The API returns the following result:

[source,console-result]
--------------------------------------------------
{
  "_shards": {
    "total": 2,
    "failed": 0,
    "successful": 2
  },
  "_index": "my-index-000001",
  "_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/]