elasticsearch/docs/java-rest/high-level/apis/bulk.asciidoc

[[java-rest-high-document-bulk]]
=== Bulk API

[[java-rest-high-document-bulk-request]]
==== Bulk Request

A `BulkRequest` can be used to execute multiple index, update and/or delete
operations using a single request.

It requires at least one operation to be added to the Bulk request:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-request]
--------------------------------------------------
<1> Creates the `BulkRequest`
<2> Adds a first `IndexRequest` to the Bulk request. See <<java-rest-high-document-index>>
for more information on how to build `IndexRequest`.
<3> Adds a second `IndexRequest`
<4> Adds a third `IndexRequest`

WARNING: The Bulk API supports only documents encoded in JSON or SMILE. Providing documents
 in any other format will result in an error.

And different operation types can be added to the same `BulkRequest`:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-request-with-mixed-operations]
--------------------------------------------------
<1> Adds a `DeleteRequest` to the `BulkRequest`. See <<java-rest-high-document-delete>>
for more information on how to build `DeleteRequest`.
<2> Adds an `UpdateRequest` to the `BulkRequest`. See <<java-rest-high-document-update>>
for more information on how to build `UpdateRequest`.
<3> Adds an `IndexRequest` using the SMILE format

==== Optional arguments
The following arguments can optionally be provided:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-request-timeout]
--------------------------------------------------
<1> Timeout to wait for the bulk request to be performed as a `TimeValue`
<2> Timeout to wait for the bulk request to be performed as a `String`

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-request-refresh]
--------------------------------------------------
<1> Refresh policy as a `WriteRequest.RefreshPolicy` instance
<2> Refresh policy as a `String`

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-request-active-shards]
--------------------------------------------------
<1> Sets the number of shard copies that must be active before proceeding with
the index/update/delete operations.
<2> Number of shard copies provided as a `ActiveShardCount`: can be `ActiveShardCount.ALL`,
`ActiveShardCount.ONE` or `ActiveShardCount.DEFAULT` (default)


[[java-rest-high-document-bulk-sync]]
==== Synchronous Execution

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-execute]
--------------------------------------------------

[[java-rest-high-document-bulk-async]]
==== Asynchronous Execution

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-execute-async]
--------------------------------------------------
<1> Called when the execution is successfully completed. The response is
provided as an argument and contains a list of individual results for each
operation that was executed. Note that one or more operations might have
failed while the others have been successfully executed.
<2> Called when the whole `BulkRequest` fails. In this case the raised
exception is provided as an argument and no operation has been executed.

[[java-rest-high-document-bulk-response]]
==== Bulk Response

The returned `BulkResponse` contains information about the executed operations and
 allows to iterate over each result as follows:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-response]
--------------------------------------------------
<1> Iterate over the results of all operations
<2> Retrieve the response of the operation (successful or not), can be `IndexResponse`,
`UpdateResponse` or `DeleteResponse` which can all be seen as `DocWriteResponse` instances
<3> Handle the response of an index operation
<4> Handle the response of a update operation
<5> Handle the response of a delete operation

The Bulk response provides a method to quickly check if one or more operation has failed:
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-has-failures]
--------------------------------------------------
<1> This method returns `true` if at least one operation failed

In such situation it is necessary to iterate over all operation results in order to check
 if the operation failed, and if so, retrieve the corresponding failure:
["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-errors]
--------------------------------------------------
<1> Indicate if a given operation failed
<2> Retrieve the failure of the failed operation