From 89e97811c64230c26747ab30280d9c1ee9df1f4d Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Fri, 17 Apr 2020 13:25:13 -0400 Subject: [PATCH] [DOCS] Document missing bulk API response parameters --- docs/reference/docs/bulk.asciidoc | 145 +++++++++++++++++++++++++++--- 1 file changed, 131 insertions(+), 14 deletions(-) diff --git a/docs/reference/docs/bulk.asciidoc b/docs/reference/docs/bulk.asciidoc index d091bd0b0c545..5bb93845137cb 100644 --- a/docs/reference/docs/bulk.asciidoc +++ b/docs/reference/docs/bulk.asciidoc @@ -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 <>. -[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 <> for more information. - [[docs-bulk-api-path-params]] ==== {api-path-parms-title} @@ -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 <> 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] +==== +:: +(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 `` +[%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 <>. ++ +This parameter is only returned for successful operations. + +`_primary_term`:: +(integer) +The primary term assigned to the document for the operation. +See <>. ++ +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}