[DOCS] Document missing bulk API response parameters (#55414)

jrodewig · web-flow · commit fb217d96eb88 · 2020-04-22T09:09:06.000-04:00
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
diff --git 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 <<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}
 
@@ -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}
