mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-21 20:35:54 +00:00
73d0a1b777
This note in the delete api about broadcasting to all shards is a leftover that should have been removed when the broadcasting feature was removed Relates to #10136
135 lines
4.3 KiB
Plaintext
135 lines
4.3 KiB
Plaintext
[[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]
|
|
--------------------------------------------------
|
|
{
|
|
"_shards" : {
|
|
"total" : 10,
|
|
"failed" : 0,
|
|
"successful" : 10
|
|
},
|
|
"found" : true,
|
|
"_index" : "twitter",
|
|
"_type" : "tweet",
|
|
"_id" : "1",
|
|
"_version" : 2,
|
|
"result: deleted"
|
|
}
|
|
--------------------------------------------------
|
|
|
|
[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.
|
|
|
|
When the `_routing` mapping is set as `required` and no routing value is
|
|
specified, the delete api will throw a `RoutingMissingException` and reject
|
|
the request.
|
|
|
|
[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 use the <<docs-delete-by-query,Delete By Query API>> to perform a
|
|
index with the automatically generated (and indexed)
|
|
field _parent, which is in the format parent_type#parent_id.
|
|
|
|
When deleting a child document its parent id must be specified, otherwise
|
|
the delete request will be rejected and a `RoutingMissingException` will be
|
|
thrown instead.
|
|
|
|
[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-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.
|
|
|
|
[float]
|
|
[[delete-refresh]]
|
|
=== Refresh
|
|
|
|
Control when the changes made by this request are visible to search. See
|
|
<<docs-refresh>>.
|
|
|
|
|
|
[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 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,js]
|
|
--------------------------------------------------
|
|
$ curl -XDELETE 'http://localhost:9200/twitter/tweet/1?timeout=5m'
|
|
--------------------------------------------------
|