Delete APIedit

Removes a JSON document from the specified index.

Requestedit

DELETE /<index>/_doc/<_id>

Descriptionedit

You use DELETE to remove a document from an index. You must specify the index name and document ID.

Optimistic concurrency controledit

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.

Versioningedit

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.

Routingedit

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:

$params = [
    'index'   => 'twitter',
    'id'      => '1',
    'routing' => 'kimchy',
];
$response = $client->delete($params);
var deleteResponse = client.Delete<Tweet>(1, d => d
    .Index("twitter")
    .Routing("kimchy")
);
response = es.delete(
    index='twitter',
    id=1,
    routing='kimchy',
)
response = client.delete(index: 'twitter', id: 1, routing: 'kimchy')
DELETE /twitter/_doc/1?routing=kimchy

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

Automatic index creationedit

If an 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 create index API.

Distributededit

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.

Wait for active shardsedit

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 here for further details and a usage example.

Refreshedit

Control when the changes made by this request are visible to search. See ?refresh.

Timeoutedit

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:

$params = [
    'index'   => 'twitter',
    'id'      => '1',
    'timeout' => '5m',
];
$response = $client->delete($params);
var deleteResponse = client.Delete<Tweet>(1, d => d
    .Index("twitter")
    .Timeout("5m")
);
response = es.delete(
    index='twitter',
    id=1,
    timeout='5m',
)
response = client.delete(index: 'twitter', id: 1, routing: 'kimchy', timeout: '5m')
DELETE /twitter/_doc/1?timeout=5m

Path parametersedit

<index>
(Required, string) Name of the target index.
<_id>
(Required, string) Unique identifier for the document.

Query parametersedit

if_seq_no
(Optional, integer) Only perform the operation if the document has this sequence number. See Optimistic concurrency control.
if_primary_term
(Optional, integer) Only perform the operation if the document has this primary term. See Optimistic concurrency control.
pipeline
(Optional, string) ID of the pipeline to use to preprocess incoming documents.
refresh
(Optional, enum) If true, Elasticsearch refreshes the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false do nothing with refreshes. Valid values: true, false, wait_for. Default: false.
routing
(Optional, string) Target the specified primary shard.
timeout
(Optional, time units) Specifies the period of time to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to 30s.
version
(Optional, integer) Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed.
version_type
(Optional, enum) Specific version type: internal, external, external_gte, force.
wait_for_active_shards

(Optional, string) The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1). Default: 1, the primary shard.

See Active shards.

Examplesedit

Delete the JSON document 1 from the twitter index:

$params = [
    'index' => 'twitter',
    'id'    => '1',
];
$response = $client->delete($params);
var deleteResponse = client.Delete<Tweet>(1, d => d.Index("twitter"));
response = es.delete(
    index='twitter',
    id=1,
)
response = client.delete(index: 'twitter', id: 1)
DELETE /twitter/_doc/1

The API returns the following result:

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