118 lines
5.3 KiB
Plaintext
118 lines
5.3 KiB
Plaintext
|
[[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
|