---
type: api
title: Delete a document
description: Remove a JSON document from the specified index.
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-delete
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-delete
products:
  - Elasticsearch
---

# Delete a document

Availability:

## Paths

- `DELETE` `/{index}/_doc/{id}`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#bearerauth)

#### Path Parameters

- `index` (string IndexName)
  The name of the target index.
- `id` (string Id)
  A unique identifier for the document.

## Description

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`

## Query String 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` (string Routing)
  A custom value used to route operations to a specific shard.
- `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`

- `_id` (string Id)
  The unique identifier for the added document.
- `_index` (string IndexName)
  The name of the index the document was added to.
- `_primary_term` (number)
  The primary term assigned to the document for the indexing operation.
- `result` (enum Result)
  The result of the indexing operation: `created` or `updated`.
  Values: `created`, `updated`, `deleted`, `not_found`, `noop`
- `_seq_no` (number SequenceNumber)
  The sequence number assigned to the document for the indexing operation.
Sequence numbers are used to ensure an older version of a document doesn't overwrite a newer version.
- `_shards` ({} ShardStatistics)
  Information about the replication process of the operation.
  - `failed` (number uint)
    The number of shards the operation or search attempted to run on but failed.
  - `successful` (number uint)
    The number of shards the operation or search succeeded on.
  - `total` (number uint)
    The number of shards the operation or search will run on overall.
  - `failures` ([] ShardFailure)
    - `index` (string IndexName)
    - `node` (string)
    - `reason` ({} ErrorCause)
      - `type` (string)
        The type of error
      - `reason` (union string) — nullable
        A human-readable explanation of the error, in English.
        One of: `string`
      - `stack_trace` (string)
        The server stack trace. Present only if the `error_trace=true` parameter was sent with the request.
      - `caused_by` ({} ErrorCause) — recursive
        Same fields as `reason` in `failures`
      - `root_cause` ([] ErrorCause) — recursive
        Same fields as `reason` in `failures`
      - `suppressed` ([] ErrorCause) — recursive
        Same fields as `reason` in `failures`
    - `shard` (number)
    - `status` (string)
    - `primary` (boolean)
  - `skipped` (number uint)
- `_version` (number VersionNumber)
  The document version, which is incremented each time the document is updated.
- `failure_store` (enum FailureStoreStatus)
  The role of the failure store in this document response
  Values: `not_applicable_or_unknown`, `used`, `not_enabled`, `failed`
- `forced_refresh` (boolean)
## Code Examples

#### Console

```console
DELETE /my-index-000001/_doc/1
```

#### JavaScript

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

#### Python

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

#### curl

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

#### Java

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

#### C#

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

#### PHP

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

#### Ruby

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

## Response Examples

#### Delete response example1

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

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