diff options
5 files changed, 223 insertions, 1 deletions
diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java index c585f2f10e..7d3919ca06 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java @@ -23,13 +23,20 @@ import org.elasticsearch.ElasticsearchException; import org.elasticsearch.action.ActionListener; import org.elasticsearch.action.DocWriteRequest; import org.elasticsearch.action.DocWriteResponse; +import org.elasticsearch.action.bulk.BulkItemResponse; +import org.elasticsearch.action.bulk.BulkRequest; +import org.elasticsearch.action.bulk.BulkResponse; import org.elasticsearch.action.delete.DeleteRequest; import org.elasticsearch.action.delete.DeleteResponse; import org.elasticsearch.action.index.IndexRequest; import org.elasticsearch.action.index.IndexResponse; +import org.elasticsearch.action.support.ActiveShardCount; import org.elasticsearch.action.support.WriteRequest; import org.elasticsearch.action.support.replication.ReplicationResponse; +import org.elasticsearch.action.update.UpdateRequest; +import org.elasticsearch.action.update.UpdateResponse; import org.elasticsearch.client.ESRestHighLevelClientTestCase; +import org.elasticsearch.client.Requests; import org.elasticsearch.client.RestHighLevelClient; import org.elasticsearch.common.unit.TimeValue; import org.elasticsearch.common.xcontent.XContentBuilder; @@ -318,4 +325,96 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { // end::delete-conflict } } + + public void testBulk() throws IOException { + RestHighLevelClient client = highLevelClient(); + { + // tag::bulk-request + BulkRequest request = new BulkRequest(); // <1> + request.add(new IndexRequest("index", "type", "0") // <2> + .source(XContentType.JSON,"field", "foo")); + request.add(new IndexRequest("index", "type", "1") // <3> + .source(XContentType.JSON,"field", "bar")); + request.add(new IndexRequest("index", "type", "2") // <4> + .source(XContentType.JSON,"field", "baz")); + // end::bulk-request + // tag::bulk-execute + BulkResponse bulkResponse = client.bulk(request); + // end::bulk-execute + assertSame(bulkResponse.status(), RestStatus.OK); + assertFalse(bulkResponse.hasFailures()); + } + { + // tag::bulk-request-with-mixed-operations + BulkRequest request = new BulkRequest(); + request.add(new DeleteRequest("index", "type", "2")); // <1> + request.add(new UpdateRequest("index", "type", "1") // <2> + .doc(XContentType.JSON,"other", "test")); + request.add(new IndexRequest("index", "type", "4") // <3> + .source(XContentType.JSON,"field", "baz")); + // end::bulk-request-with-mixed-operations + BulkResponse bulkResponse = client.bulk(request); + assertSame(bulkResponse.status(), RestStatus.OK); + assertFalse(bulkResponse.hasFailures()); + + // tag::bulk-response + for (BulkItemResponse bulkItemResponse : bulkResponse) { // <1> + DocWriteResponse itemResponse = bulkItemResponse.getResponse(); // <2> + + if (bulkItemResponse.getOpType() == DocWriteRequest.OpType.INDEX + || bulkItemResponse.getOpType() == DocWriteRequest.OpType.CREATE) { // <3> + IndexResponse indexResponse = (IndexResponse)itemResponse; + + } else if (bulkItemResponse.getOpType() == DocWriteRequest.OpType.UPDATE) { // <4> + UpdateResponse updateResponse = (UpdateResponse)itemResponse; + + } else if (bulkItemResponse.getOpType() == DocWriteRequest.OpType.DELETE) { // <5> + DeleteResponse deleteResponse = (DeleteResponse) itemResponse; + } + } + // end::bulk-response + // tag::bulk-has-failures + if (bulkResponse.hasFailures()) { // <1> + + } + // end::bulk-has-failures + // tag::bulk-errors + for (BulkItemResponse bulkItemResponse : bulkResponse) { + if (bulkItemResponse.isFailed()) { // <1> + BulkItemResponse.Failure failure = bulkItemResponse.getFailure(); // <2> + + } + } + // end::bulk-errors + } + { + BulkRequest request = new BulkRequest(); + // tag::bulk-request-timeout + request.timeout(TimeValue.timeValueMinutes(2)); // <1> + request.timeout("2m"); // <2> + // end::bulk-request-timeout + // tag::bulk-request-refresh + request.setRefreshPolicy(WriteRequest.RefreshPolicy.WAIT_UNTIL); // <1> + request.setRefreshPolicy("wait_for"); // <2> + // end::bulk-request-refresh + // tag::bulk-request-active-shards + request.waitForActiveShards(2); // <1> + request.waitForActiveShards(ActiveShardCount.ALL); // <2> + // end::bulk-request-active-shards + + // tag::bulk-execute-async + client.bulkAsync(request, new ActionListener<BulkResponse>() { + @Override + public void onResponse(BulkResponse bulkResponse) { + // <1> + } + + @Override + public void onFailure(Exception e) { + // <2> + } + }); + // end::bulk-execute-async + } + } } 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 |