[DOCS] Document missing bulk API response parameters (#55414)
Documents several parameters missing from the bulk API's response body docs. Also moves several response-related chunks of text to the response body section. Relates to #55237
This commit is contained in:
James Rodewig
GitHub
parent
50a5afed15
commit
414f9c98f3
|
|
@ -79,11 +79,6 @@ Client libraries using this protocol should try and strive to do
|
|||
something similar on the client side, and reduce buffering as much as
|
||||
possible.
|
||||
|
||||
The response to a bulk action is a large JSON structure with
|
||||
the individual results of each action performed,
|
||||
in the same order as the actions that appeared in the request.
|
||||
The failure of a single action does not affect the remaining actions.
|
||||
|
||||
There is no "correct" number of actions to perform in a single bulk request.
|
||||
Experiment with different settings to find the optimal size for your particular workload.
|
||||
|
||||
|
|
@ -183,12 +178,6 @@ participate in the `_bulk` request at all.
|
|||
|
||||
See <<url-access-control>>.
|
||||
|
||||
[float]
|
||||
[[bulk-partial-responses]]
|
||||
===== Partial responses
|
||||
To ensure fast responses, the bulk API will respond with partial results if one or more shards fail.
|
||||
See <<shard-failures, Shard failures>> for more information.
|
||||
|
||||
[[docs-bulk-api-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
|
|
@ -214,6 +203,212 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=timeout]
|
|||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]
|
||||
|
||||
[[bulk-api-request-body]]
|
||||
==== {api-request-body-title}
|
||||
The request body contains a newline-delimited list of `create`, `delete`, `index`,
|
||||
and `update` actions and their associated source data.
|
||||
|
||||
`create`::
|
||||
(Optional, string)
|
||||
Indexes the specified document if it does not already exist.
|
||||
The following line must contain the source data to be indexed.
|
||||
+
|
||||
--
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=bulk-index]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=bulk-id]
|
||||
--
|
||||
|
||||
`delete`::
|
||||
(Optional, string)
|
||||
Removes the specified document from the index.
|
||||
+
|
||||
--
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=bulk-index]
|
||||
|
||||
`_id`::
|
||||
(Required, string)
|
||||
The document ID.
|
||||
--
|
||||
|
||||
`index`::
|
||||
(Optional, string)
|
||||
Indexes the specified document.
|
||||
If the document exists, replaces the document and increments the version.
|
||||
The following line must contain the source data to be indexed.
|
||||
+
|
||||
--
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=bulk-index]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=bulk-id]
|
||||
--
|
||||
|
||||
`update`::
|
||||
(Optional, string)
|
||||
Performs a partial document update.
|
||||
The following line must contain the partial document and update options.
|
||||
+
|
||||
--
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=bulk-index]
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=bulk-id]
|
||||
--
|
||||
|
||||
`doc`::
|
||||
(Optional, object)
|
||||
The partial document to index.
|
||||
Required for `update` operations.
|
||||
|
||||
`<fields>`::
|
||||
(Optional, object)
|
||||
The document source to index.
|
||||
Required for `create` and `index` operations.
|
||||
|
||||
[role="child_attributes"]
|
||||
[[bulk-api-response-body]]
|
||||
==== {api-response-body-title}
|
||||
|
||||
The bulk API's response contains the individual results of each operation in the
|
||||
request, returned in the order submitted. The success or failure of an
|
||||
individual operation does not affect other operations in the request.
|
||||
|
||||
[[bulk-partial-responses]]
|
||||
.Partial responses
|
||||
****
|
||||
To ensure fast responses, the bulk API will respond with partial results if one
|
||||
or more shards fail. See <<shard-failures, Shard failures>> for more
|
||||
information.
|
||||
****
|
||||
|
||||
`took`::
|
||||
(integer)
|
||||
How long, in milliseconds, it took to process the bulk request.
|
||||
|
||||
`errors`::
|
||||
(boolean)
|
||||
If `true`, one or more of the operations in the bulk request did not complete
|
||||
successfully.
|
||||
|
||||
`items`::
|
||||
(array of objects)
|
||||
Contains the result of each operation in the bulk request, in the order they
|
||||
were submitted.
|
||||
+
|
||||
.Properties of `items` objects
|
||||
[%collapsible%open]
|
||||
====
|
||||
<action>::
|
||||
(object)
|
||||
The parameter name is an action associated with the operation. Possible values
|
||||
are `create`, `delete`, `index`, and `update`.
|
||||
+
|
||||
The parameter value is an object that contains information for the associated
|
||||
operation.
|
||||
+
|
||||
.Properties of `<action>`
|
||||
[%collapsible%open]
|
||||
=====
|
||||
`_index`::
|
||||
(string)
|
||||
The index name or alias associated with the operation.
|
||||
|
||||
`_type`::
|
||||
(string)
|
||||
The document type associated with the operation. {es} indices now support a
|
||||
single document type: `_doc`. See <<removal-of-types>>.
|
||||
|
||||
`_id`::
|
||||
(integer)
|
||||
The document ID associated with the operation.
|
||||
|
||||
`_version`::
|
||||
(integer)
|
||||
The document version associated with the operation. The document version is
|
||||
incremented each time the document is updated.
|
||||
+
|
||||
This parameter is only returned for successful actions.
|
||||
|
||||
`result`::
|
||||
(string)
|
||||
Result of the operation. Successful values are `created`, `deleted`, and
|
||||
`updated`.
|
||||
+
|
||||
This parameter is only returned for successful operations.
|
||||
|
||||
`_shards`::
|
||||
(object)
|
||||
Contains shard information for the operation.
|
||||
+
|
||||
This parameter is only returned for successful operations.
|
||||
+
|
||||
.Properties of `_shards`
|
||||
[%collapsible%open]
|
||||
======
|
||||
`total`::
|
||||
(integer)
|
||||
Number of shards the operation attempted to execute on.
|
||||
|
||||
`successful`::
|
||||
(integer)
|
||||
Number of shards the operation succeeded on.
|
||||
|
||||
`failed`::
|
||||
(integer)
|
||||
Number of shards the operation attempted to execute on but failed.
|
||||
======
|
||||
|
||||
`_seq_no`::
|
||||
(integer)
|
||||
The sequence number assigned to the document for the operation.
|
||||
Sequence numbers are used to ensure an older version of a document
|
||||
doesn’t overwrite a newer version. See <<optimistic-concurrency-control-index>>.
|
||||
+
|
||||
This parameter is only returned for successful operations.
|
||||
|
||||
`_primary_term`::
|
||||
(integer)
|
||||
The primary term assigned to the document for the operation.
|
||||
See <<optimistic-concurrency-control-index>>.
|
||||
+
|
||||
This parameter is only returned for successful operations.
|
||||
|
||||
`status`::
|
||||
(integer)
|
||||
HTTP status code returned for the operation.
|
||||
|
||||
`error`::
|
||||
(object)
|
||||
Contains additional information about the failed operation.
|
||||
+
|
||||
The parameter is only returned for failed operations.
|
||||
+
|
||||
.Properties of `error`
|
||||
[%collapsible%open]
|
||||
======
|
||||
`type`::
|
||||
(string)
|
||||
Error type for the operation.
|
||||
|
||||
`reason`::
|
||||
(string)
|
||||
Reason for the failed operation.
|
||||
|
||||
`index_uuid`::
|
||||
(string)
|
||||
The universally unique identifier (UUID) of the index associated with the failed
|
||||
operation.
|
||||
|
||||
`shard`::
|
||||
(string)
|
||||
ID of the shard associated with the failed operation.
|
||||
|
||||
`index`::
|
||||
(string)
|
||||
The index name or alias associated with the failed operation.
|
||||
======
|
||||
=====
|
||||
====
|
||||
|
||||
[[docs-bulk-api-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
|
|
|
|||
|
|
@ -359,6 +359,13 @@ tag::help[]
|
|||
to `false`.
|
||||
end::help[]
|
||||
|
||||
tag::bulk-id[]
|
||||
`_id`::
|
||||
(Optional, string)
|
||||
The document ID.
|
||||
If no ID is specified, a document ID is automatically generated.
|
||||
end::bulk-id[]
|
||||
|
||||
tag::if_primary_term[]
|
||||
`if_primary_term`::
|
||||
(Optional, integer) Only perform the operation if the document has
|
||||
|
|
|
|||
Loading…
Reference in New Issue