[Docs] Document Bulk API for Java High Level REST Client (#25532)
This commit adds documentation for Java High Level REST Client's Bulk API.
This commit is contained in:
Tanguy Leroux
GitHub
parent
141aa226f4
commit
3da3632021
|
|
@ -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
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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!:
|
||||
|
|
|
|||
|
|
@ -0,0 +1,4 @@
|
|||
[[java-rest-high-document-update]]
|
||||
=== Update API
|
||||
|
||||
See https://github.com/elastic/elasticsearch/pull/25536
|
||||
Loading…
Reference in New Issue