Delete a document

DELETE /{index}/_doc/{id}

Remove a JSON document from the specified index.

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.

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.

Versioning

Each document indexed is versioned. When deleting a document, the version can be specified to make sure the relevant document you are trying to delete is actually being deleted and it has not changed in the meantime. Every write operation run 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.

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:

DELETE /my-index-000001/_doc/1?routing=shard-1

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.

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.

Required authorization

Index privileges: delete

Path Parameters

Query Parameters

if_primary_term number

Only perform the operation if the document has this primary term.

if_seq_no number SequenceNumber

Only perform the operation if the document has this sequence number.

refresh enum Refresh · default: false

If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If wait_for, it waits for a refresh to make this operation visible to search. If false, it does nothing with refreshes.

Values: true false wait_for

routing union Routing

A custom value used to route operations to a specific shard. Not allowed when index.slice.enabled is true for the target index; use _slice instead.

One of: string or string[]

timeout string Duration · default: 1m

The period to wait for active shards.

This parameter is useful for situations where the primary shard assigned to perform the delete operation might not be available when the delete operation runs. 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.

version number VersionNumber

An explicit version number for concurrency control. It must match the current version of the document for the request to succeed.

version_type enum VersionType

The version type.

Supported values include:

internal: Use internal versioning that starts at 1 and increments with each update or delete.
external: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.
external_gte: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document. NOTE: The external_gte version type is meant for special use cases and should be used with care. If used incorrectly, it can result in loss of data.

Values: internal external external_gte

wait_for_active_shards WaitForActiveShards · default: 1

The minimum number of shard copies that must be active before proceeding with the operation. You can set it to all or any positive integer up to the total number of shards in the index (number_of_replicas+1). The default value of 1 means it waits for each primary shard to be active.

Values: all index-setting

Response

application/json

Examples

A successful response from DELETE /my-index-000001/_doc/1, which deletes the JSON document 1 from the my-index-000001 index.

Request Console 1 / 8 languages

Console Kibana Dev Tools

DELETE /my-index-000001/_doc/1

JavaScript Elasticsearch JavaScript Client

const response = await client.delete({
  index: "my-index-000001",
  id: 1,
});

Python Elasticsearch Python Client

resp = client.delete(
    index="my-index-000001",
    id="1",
)

curl Shell

curl -X DELETE "$ELASTICSEARCH_URL/my-index-000001/_doc/1" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY"

Java Elasticsearch Java Client

client.delete(d -> d
    .id("1")
    .index("my-index-000001")
);

C# Elasticsearch .NET Client

var response = await client.DeleteAsync(index: "my-index-000001", id: "1");

PHP Elasticsearch PHP Client

$resp = $client->delete([
    "index" => "my-index-000001",
    "id" => "1",
]);

Ruby Elasticsearch Ruby Client

response = client.delete(
  index: "my-index-000001",
  id: "1"
)

Response

{
  "_shards": {
    "total": 2,
    "failed": 0,
    "successful": 2
  },
  "_index": "my-index-000001",
  "_id": "1",
  "_version": 2,
  "_primary_term": 1,
  "_seq_no": 5,
  "result": "deleted"
}

Required authorization

Path Parameters { index , id , }

Query Parameters { if_primary_term , if_seq_no , refresh , routing , timeout , version , version_type , wait_for_active_shards , }

Response

Path Parameters

Query Parameters