Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCS] Reformat doc delete API reference. #45422

Merged
merged 6 commits into from
Aug 13, 2019
Merged

[DOCS] Reformat doc delete API reference. #45422

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d48850a
[DOCS] Reformat doc delete API reference.
debadair Aug 10, 2019
8873f5e
Edits to sync with index API.
debadair Aug 12, 2019
c5232d3
Fixed common parms includes.
debadair Aug 12, 2019
ccd5e18
Added timeout tag to common parms
debadair Aug 13, 2019
21d4433
Moved description where it belongs.
debadair Aug 13, 2019
40f73c2
Removed parens.
debadair Aug 13, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 101 additions & 54 deletions docs/reference/docs/delete.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,53 +1,35 @@
[[docs-delete]]
=== Delete API
++++
<titleabbrev>Delete</titleabbrev>
++++

The delete API allows to delete a JSON document from a specific
index based on its id. The following example deletes the JSON document
from an index called `twitter` with ID `1`:
Removes a JSON document from the specified index.

[source,js]
--------------------------------------------------
DELETE /twitter/_doc/1
--------------------------------------------------
// CONSOLE
// TEST[setup:twitter]
[[docs-delete-api-request]]
==== {api-request-title}

The result of the above delete operation is:
`DELETE /<index>/_doc/<_id>`

[source,js]
--------------------------------------------------
{
"_shards" : {
"total" : 2,
"failed" : 0,
"successful" : 2
},
"_index" : "twitter",
"_type" : "_doc",
"_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/]
[[docs-delete-api-desc]]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This needs to be relocated below the request section but above the path parms section.

==== {api-description-title}

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

[float]
[[optimistic-concurrency-control-delete]]
==== Optimistic concurrency control
===== 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
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.
and a status code of 409. See <<optimistic-concurrency-control>> for more details.

[float]
[[delete-versioning]]
==== 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
Expand All @@ -60,11 +42,17 @@ determined by the `index.gc_deletes` index setting and defaults to 60 seconds.

[float]
[[delete-routing]]
==== 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:

When indexing using the ability to control the routing, in order to
delete a document, the routing value should also be provided. For
example:

////
Example to delete with routing
Expand All @@ -87,34 +75,29 @@ DELETE /twitter/_doc/1?routing=kimchy
// CONSOLE
// TEST[continued]

The above will delete a tweet with id `1`, but will be routed based on the
user. Note that 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.
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.

[float]
[[delete-index-creation]]
==== Automatic index creation
===== Automatic index creation

If an <<docs-index_,external versioning variant>> is used,
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).
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>>.

[float]
[[delete-distributed]]
==== 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
===== 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
Expand All @@ -124,15 +107,14 @@ example.

[float]
[[delete-refresh]]
==== Refresh
===== Refresh

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


[float]
[[delete-timeout]]
==== 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
Expand All @@ -149,3 +131,68 @@ DELETE /twitter/_doc/1?timeout=5m
--------------------------------------------------
// CONSOLE
// TEST[setup:twitter]

[[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::{docdir}/rest-api/common-parms.asciidoc[tag=doc-seq-no]

include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-primary-term]

include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-pipeline]

include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-refresh]

include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-routing]

include::{docdir}/rest-api/common-parms.asciidoc[tag=timeout]

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

include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-version-type]

include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-wait-for-active-shards]

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

Delete the JSON document `1` from the `twitter` index:

[source,js]
--------------------------------------------------
DELETE /twitter/_doc/1
--------------------------------------------------
// CONSOLE
// TEST[setup:twitter]

The API returns the following result:

[source,js]
--------------------------------------------------
{
"_shards" : {
"total" : 2,
"failed" : 0,
"successful" : 2
},
"_index" : "twitter",
"_type" : "_doc",
"_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/]
2 changes: 2 additions & 0 deletions docs/reference/rest-api/common-parms.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,10 +123,12 @@ end::doc-wait-for-active-shards[]

tag::timeoutparms[]

tag::timeout[]
`timeout`::
(Optional, <<time-units, 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`.
end::timeout[]

tag::master-timeout[]
`master_timeout`::
Expand Down