From 414f9c98f3576efb848b64f9e900e66489b391e7 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 22 Apr 2020 09:48:03 -0400 Subject: [PATCH] [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 --- docs/reference/docs/bulk.asciidoc | 217 +++++++++++++++++- docs/reference/rest-api/common-parms.asciidoc | 7 + 2 files changed, 213 insertions(+), 11 deletions(-) diff --git a/docs/reference/docs/bulk.asciidoc b/docs/reference/docs/bulk.asciidoc index 3e825dddeb4..4a3f4a64550 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} @@ -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. + +``:: +(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 <> 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] +==== +:: +(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. + +`_type`:: +(string) +The document type associated with the operation. {es} indices now support a +single document type: `_doc`. See <>. + +`_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} diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc index 15f9fb8ad9b..bdcafd34bdd 100644 --- a/docs/reference/rest-api/common-parms.asciidoc +++ b/docs/reference/rest-api/common-parms.asciidoc @@ -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