Skip to content

Commit fb217d9

Browse files
authored
[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
1 parent 2d55592 commit fb217d9

File tree

1 file changed

+131
-14
lines changed

1 file changed

+131
-14
lines changed

docs/reference/docs/bulk.asciidoc

Lines changed: 131 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -79,11 +79,6 @@ Client libraries using this protocol should try and strive to do
7979
something similar on the client side, and reduce buffering as much as
8080
possible.
8181

82-
The response to a bulk action is a large JSON structure with
83-
the individual results of each action performed,
84-
in the same order as the actions that appeared in the request.
85-
The failure of a single action does not affect the remaining actions.
86-
8782
There is no "correct" number of actions to perform in a single bulk request.
8883
Experiment with different settings to find the optimal size for your particular workload.
8984

@@ -183,12 +178,6 @@ participate in the `_bulk` request at all.
183178

184179
See <<url-access-control>>.
185180

186-
[float]
187-
[[bulk-partial-responses]]
188-
===== Partial responses
189-
To ensure fast responses, the bulk API will respond with partial results if one or more shards fail.
190-
See <<shard-failures, Shard failures>> for more information.
191-
192181
[[docs-bulk-api-path-params]]
193182
==== {api-path-parms-title}
194183

@@ -275,17 +264,145 @@ Required for `update` operations.
275264
The document source to index.
276265
Required for `create` and `index` operations.
277266

267+
[role="child_attributes"]
278268
[[bulk-api-response-body]]
279269
==== {api-response-body-title}
280270

271+
The bulk API's response contains the individual results of each operation in the
272+
request, returned in the order submitted. The success or failure of an
273+
individual operation does not affect other operations in the request.
274+
275+
[[bulk-partial-responses]]
276+
.Partial responses
277+
****
278+
To ensure fast responses, the bulk API will respond with partial results if one
279+
or more shards fail. See <<shard-failures, Shard failures>> for more
280+
information.
281+
****
282+
281283
`took`::
282-
(milliseconds) How long it took to process the bulk request.
284+
(integer)
285+
How long, in milliseconds, it took to process the bulk request.
283286

284287
`errors`::
285-
(boolean) If `true`, one or more of the operations in the bulk request did not complete successfully.
288+
(boolean)
289+
If `true`, one or more of the operations in the bulk request did not complete
290+
successfully.
286291

287292
`items`::
288-
(array) The result of each operation in the bulk request in the order they were requested.
293+
(array of objects)
294+
Contains the result of each operation in the bulk request, in the order they
295+
were submitted.
296+
+
297+
.Properties of `items` objects
298+
[%collapsible%open]
299+
====
300+
<action>::
301+
(object)
302+
The parameter name is an action associated with the operation. Possible values
303+
are `create`, `delete`, `index`, and `update`.
304+
+
305+
The parameter value is an object that contains information for the associated
306+
operation.
307+
+
308+
.Properties of `<action>`
309+
[%collapsible%open]
310+
=====
311+
`_index`::
312+
(string)
313+
The index name or alias associated with the operation.
314+
315+
`_id`::
316+
(integer)
317+
The document ID associated with the operation.
318+
319+
`_version`::
320+
(integer)
321+
The document version associated with the operation. The document version is
322+
incremented each time the document is updated.
323+
+
324+
This parameter is only returned for successful actions.
325+
326+
`result`::
327+
(string)
328+
Result of the operation. Successful values are `created`, `deleted`, and
329+
`updated`.
330+
+
331+
This parameter is only returned for successful operations.
332+
333+
`_shards`::
334+
(object)
335+
Contains shard information for the operation.
336+
+
337+
This parameter is only returned for successful operations.
338+
+
339+
.Properties of `_shards`
340+
[%collapsible%open]
341+
======
342+
`total`::
343+
(integer)
344+
Number of shards the operation attempted to execute on.
345+
346+
`successful`::
347+
(integer)
348+
Number of shards the operation succeeded on.
349+
350+
`failed`::
351+
(integer)
352+
Number of shards the operation attempted to execute on but failed.
353+
======
354+
355+
`_seq_no`::
356+
(integer)
357+
The sequence number assigned to the document for the operation.
358+
Sequence numbers are used to ensure an older version of a document
359+
doesn’t overwrite a newer version. See <<optimistic-concurrency-control-index>>.
360+
+
361+
This parameter is only returned for successful operations.
362+
363+
`_primary_term`::
364+
(integer)
365+
The primary term assigned to the document for the operation.
366+
See <<optimistic-concurrency-control-index>>.
367+
+
368+
This parameter is only returned for successful operations.
369+
370+
`status`::
371+
(integer)
372+
HTTP status code returned for the operation.
373+
374+
`error`::
375+
(object)
376+
Contains additional information about the failed operation.
377+
+
378+
The parameter is only returned for failed operations.
379+
+
380+
.Properties of `error`
381+
[%collapsible%open]
382+
======
383+
`type`::
384+
(string)
385+
Error type for the operation.
386+
387+
`reason`::
388+
(string)
389+
Reason for the failed operation.
390+
391+
`index_uuid`::
392+
(string)
393+
The universally unique identifier (UUID) of the index associated with the failed
394+
operation.
395+
396+
`shard`::
397+
(string)
398+
ID of the shard associated with the failed operation.
399+
400+
`index`::
401+
(string)
402+
The index name or alias associated with the failed operation.
403+
======
404+
=====
405+
====
289406

290407
[[docs-bulk-api-example]]
291408
==== {api-examples-title}

0 commit comments

Comments
 (0)