diff options
author | Tanguy Leroux <tlrx.dev@gmail.com> | 2017-07-05 09:26:26 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2017-07-05 09:26:26 +0200 |
commit | 3da3632021925741624b4144f3062a1fd4a92fa1 (patch) | |
tree | 5e0644579c408b0788e9d6fd8bde5081d9ba6fa1 /docs/java-rest/high-level | |
parent | 141aa226f4159ad57640a2029fa6ee29679d83f3 (diff) |
[Docs] Document Bulk API for Java High Level REST Client (#25532)
This commit adds documentation for Java High Level REST Client's Bulk API.
Diffstat (limited to 'docs/java-rest/high-level')
-rw-r--r-- | docs/java-rest/high-level/apis.asciidoc | 2 | ||||
-rw-r--r-- | docs/java-rest/high-level/apis/bulk.asciidoc | 117 | ||||
-rw-r--r-- | docs/java-rest/high-level/apis/index.asciidoc | 2 | ||||
-rw-r--r-- | docs/java-rest/high-level/apis/update.asciidoc | 4 |
4 files changed, 124 insertions, 1 deletions
diff --git a/docs/java-rest/high-level/apis.asciidoc b/docs/java-rest/high-level/apis.asciidoc index 25c1b9f7c4..7693dd13ce 100644 --- a/docs/java-rest/high-level/apis.asciidoc +++ b/docs/java-rest/high-level/apis.asciidoc @@ -10,7 +10,7 @@ The Java High Level REST Client supports the following APIs: * Update API -* Bulk API +* <<java-rest-high-document-bulk>> * Search API diff --git a/docs/java-rest/high-level/apis/bulk.asciidoc b/docs/java-rest/high-level/apis/bulk.asciidoc new file mode 100644 index 0000000000..07119fb4b9 --- /dev/null +++ b/docs/java-rest/high-level/apis/bulk.asciidoc @@ -0,0 +1,117 @@ +[[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 diff --git a/docs/java-rest/high-level/apis/index.asciidoc b/docs/java-rest/high-level/apis/index.asciidoc index 94ed89c0fa..475b18dcf4 100644 --- a/docs/java-rest/high-level/apis/index.asciidoc +++ b/docs/java-rest/high-level/apis/index.asciidoc @@ -1,6 +1,8 @@ :doc-tests: {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation include::_index.asciidoc[] +include::update.asciidoc[] include::delete.asciidoc[] +include::bulk.asciidoc[] :doc-tests!: diff --git a/docs/java-rest/high-level/apis/update.asciidoc b/docs/java-rest/high-level/apis/update.asciidoc new file mode 100644 index 0000000000..79c4121b9f --- /dev/null +++ b/docs/java-rest/high-level/apis/update.asciidoc @@ -0,0 +1,4 @@ +[[java-rest-high-document-update]] +=== Update API + +See https://github.com/elastic/elasticsearch/pull/25536
\ No newline at end of file |