Skip to content

[DOCS] Document missing bulk API response parameters #55414

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.

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

Merged
merged 1 commit into from
Apr 22, 2020
Merged
Changes from all commits
Commits
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
145 changes: 131 additions & 14 deletions docs/reference/docs/bulk.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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}

Expand Down Expand Up @@ -275,17 +264,145 @@ Required for `update` operations.
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`::
(milliseconds) How long it took to process the bulk request.
(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.
(boolean)
If `true`, one or more of the operations in the bulk request did not complete
successfully.

`items`::
(array) The result of each operation in the bulk request in the order they were requested.
(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.

`_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}
Expand Down