diff --git a/buildSrc/src/main/resources/checkstyle_suppressions.xml b/buildSrc/src/main/resources/checkstyle_suppressions.xml index f36e8c0581ee8..be1b25a7310e3 100644 --- a/buildSrc/src/main/resources/checkstyle_suppressions.xml +++ b/buildSrc/src/main/resources/checkstyle_suppressions.xml @@ -25,7 +25,6 @@ Truly temporary suppressions suppression of snippets included in documentation that are so wide that they scroll. --> - 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 1d31a0e863451..cb1890c7789a1 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 @@ -714,14 +714,15 @@ public void testBulk() throws Exception { for (BulkItemResponse bulkItemResponse : bulkResponse) { // <1> DocWriteResponse itemResponse = bulkItemResponse.getResponse(); // <2> - if (bulkItemResponse.getOpType() == DocWriteRequest.OpType.INDEX - || bulkItemResponse.getOpType() == DocWriteRequest.OpType.CREATE) { // <3> + switch (bulkItemResponse.getOpType()) { + case INDEX: // <3> + case CREATE: IndexResponse indexResponse = (IndexResponse) itemResponse; - - } else if (bulkItemResponse.getOpType() == DocWriteRequest.OpType.UPDATE) { // <4> + break; + case UPDATE: // <4> UpdateResponse updateResponse = (UpdateResponse) itemResponse; - - } else if (bulkItemResponse.getOpType() == DocWriteRequest.OpType.DELETE) { // <5> + break; + case DELETE: // <5> DeleteResponse deleteResponse = (DeleteResponse) itemResponse; } } @@ -734,8 +735,8 @@ public void testBulk() throws Exception { // tag::bulk-errors for (BulkItemResponse bulkItemResponse : bulkResponse) { if (bulkItemResponse.isFailed()) { // <1> - BulkItemResponse.Failure failure = bulkItemResponse.getFailure(); // <2> - + BulkItemResponse.Failure failure = + bulkItemResponse.getFailure(); // <2> } } // end::bulk-errors @@ -844,8 +845,10 @@ public void testReindex() throws Exception { // tag::reindex-request-remote request.setRemoteInfo( new RemoteInfo( - "https", "localhost", 9002, null, new BytesArray(new MatchAllQueryBuilder().toString()), - "user", "pass", Collections.emptyMap(), new TimeValue(100, TimeUnit.MILLISECONDS), + "https", "localhost", 9002, null, + new BytesArray(new MatchAllQueryBuilder().toString()), + "user", "pass", Collections.emptyMap(), + new TimeValue(100, TimeUnit.MILLISECONDS), new TimeValue(100, TimeUnit.SECONDS) ) ); // <1> @@ -866,7 +869,8 @@ public void testReindex() throws Exception { // tag::reindex-execute - BulkByScrollResponse bulkResponse = client.reindex(request, RequestOptions.DEFAULT); + BulkByScrollResponse bulkResponse = + client.reindex(request, RequestOptions.DEFAULT); // end::reindex-execute assertSame(0, bulkResponse.getSearchFailures().size()); assertSame(0, bulkResponse.getBulkFailures().size()); @@ -883,9 +887,12 @@ public void testReindex() throws Exception { long bulkRetries = bulkResponse.getBulkRetries(); // <10> long searchRetries = bulkResponse.getSearchRetries(); // <11> TimeValue throttledMillis = bulkResponse.getStatus().getThrottled(); // <12> - TimeValue throttledUntilMillis = bulkResponse.getStatus().getThrottledUntil(); // <13> - List searchFailures = bulkResponse.getSearchFailures(); // <14> - List bulkFailures = bulkResponse.getBulkFailures(); // <15> + TimeValue throttledUntilMillis = + bulkResponse.getStatus().getThrottledUntil(); // <13> + List searchFailures = + bulkResponse.getSearchFailures(); // <14> + List bulkFailures = + bulkResponse.getBulkFailures(); // <15> // end::reindex-response } { @@ -893,8 +900,9 @@ public void testReindex() throws Exception { request.setSourceIndices("source1"); request.setDestIndex("dest"); + ActionListener listener; // tag::reindex-execute-listener - ActionListener listener = new ActionListener() { + listener = new ActionListener() { @Override public void onResponse(BulkByScrollResponse bulkResponse) { // <1> @@ -943,8 +951,9 @@ public void testReindexRethrottle() throws Exception { // end::rethrottle-request-execution } + ActionListener listener; // tag::rethrottle-request-async-listener - ActionListener listener = new ActionListener() { + listener = new ActionListener() { @Override public void onResponse(ListTasksResponse response) { // <1> @@ -963,9 +972,12 @@ public void onFailure(Exception e) { RethrottleRequest request = new RethrottleRequest(taskId); // tag::rethrottle-execute-async - client.reindexRethrottleAsync(request, RequestOptions.DEFAULT, listener); // <1> - client.updateByQueryRethrottleAsync(request, RequestOptions.DEFAULT, listener); // <2> - client.deleteByQueryRethrottleAsync(request, RequestOptions.DEFAULT, listener); // <3> + client.reindexRethrottleAsync(request, + RequestOptions.DEFAULT, listener); // <1> + client.updateByQueryRethrottleAsync(request, + RequestOptions.DEFAULT, listener); // <2> + client.deleteByQueryRethrottleAsync(request, + RequestOptions.DEFAULT, listener); // <3> // end::rethrottle-execute-async assertTrue(latch.await(30L, TimeUnit.SECONDS)); } @@ -993,7 +1005,8 @@ public void testUpdateByQuery() throws Exception { } { // tag::update-by-query-request - UpdateByQueryRequest request = new UpdateByQueryRequest("source1", "source2"); // <1> + UpdateByQueryRequest request = + new UpdateByQueryRequest("source1", "source2"); // <1> // end::update-by-query-request // tag::update-by-query-request-conflicts request.setConflicts("proceed"); // <1> @@ -1037,7 +1050,8 @@ public void testUpdateByQuery() throws Exception { // end::update-by-query-request-indicesOptions // tag::update-by-query-execute - BulkByScrollResponse bulkResponse = client.updateByQuery(request, RequestOptions.DEFAULT); + BulkByScrollResponse bulkResponse = + client.updateByQuery(request, RequestOptions.DEFAULT); // end::update-by-query-execute assertSame(0, bulkResponse.getSearchFailures().size()); assertSame(0, bulkResponse.getBulkFailures().size()); @@ -1053,17 +1067,21 @@ public void testUpdateByQuery() throws Exception { long bulkRetries = bulkResponse.getBulkRetries(); // <9> long searchRetries = bulkResponse.getSearchRetries(); // <10> TimeValue throttledMillis = bulkResponse.getStatus().getThrottled(); // <11> - TimeValue throttledUntilMillis = bulkResponse.getStatus().getThrottledUntil(); // <12> - List searchFailures = bulkResponse.getSearchFailures(); // <13> - List bulkFailures = bulkResponse.getBulkFailures(); // <14> + TimeValue throttledUntilMillis = + bulkResponse.getStatus().getThrottledUntil(); // <12> + List searchFailures = + bulkResponse.getSearchFailures(); // <13> + List bulkFailures = + bulkResponse.getBulkFailures(); // <14> // end::update-by-query-response } { UpdateByQueryRequest request = new UpdateByQueryRequest(); request.indices("source1"); + ActionListener listener; // tag::update-by-query-execute-listener - ActionListener listener = new ActionListener() { + listener = new ActionListener() { @Override public void onResponse(BulkByScrollResponse bulkResponse) { // <1> @@ -1110,7 +1128,8 @@ public void testDeleteByQuery() throws Exception { } { // tag::delete-by-query-request - DeleteByQueryRequest request = new DeleteByQueryRequest("source1", "source2"); // <1> + DeleteByQueryRequest request = + new DeleteByQueryRequest("source1", "source2"); // <1> // end::delete-by-query-request // tag::delete-by-query-request-conflicts request.setConflicts("proceed"); // <1> @@ -1144,7 +1163,8 @@ public void testDeleteByQuery() throws Exception { // end::delete-by-query-request-indicesOptions // tag::delete-by-query-execute - BulkByScrollResponse bulkResponse = client.deleteByQuery(request, RequestOptions.DEFAULT); + BulkByScrollResponse bulkResponse = + client.deleteByQuery(request, RequestOptions.DEFAULT); // end::delete-by-query-execute assertSame(0, bulkResponse.getSearchFailures().size()); assertSame(0, bulkResponse.getBulkFailures().size()); @@ -1159,17 +1179,21 @@ public void testDeleteByQuery() throws Exception { long bulkRetries = bulkResponse.getBulkRetries(); // <8> long searchRetries = bulkResponse.getSearchRetries(); // <9> TimeValue throttledMillis = bulkResponse.getStatus().getThrottled(); // <10> - TimeValue throttledUntilMillis = bulkResponse.getStatus().getThrottledUntil(); // <11> - List searchFailures = bulkResponse.getSearchFailures(); // <12> - List bulkFailures = bulkResponse.getBulkFailures(); // <13> + TimeValue throttledUntilMillis = + bulkResponse.getStatus().getThrottledUntil(); // <11> + List searchFailures = + bulkResponse.getSearchFailures(); // <12> + List bulkFailures = + bulkResponse.getBulkFailures(); // <13> // end::delete-by-query-response } { DeleteByQueryRequest request = new DeleteByQueryRequest(); request.indices("source1"); + ActionListener listener; // tag::delete-by-query-execute-listener - ActionListener listener = new ActionListener() { + listener = new ActionListener() { @Override public void onResponse(BulkByScrollResponse bulkResponse) { // <1> @@ -1434,14 +1458,17 @@ public void afterBulk(long executionId, BulkRequest request, } @Override - public void afterBulk(long executionId, BulkRequest request, Throwable failure) { + public void afterBulk(long executionId, BulkRequest request, + Throwable failure) { // <4> } }; BiConsumer> bulkConsumer = - (request, bulkListener) -> highLevelClient().bulkAsync(request, RequestOptions.DEFAULT, bulkListener); - BulkProcessor bulkProcessor = BulkProcessor.builder(bulkConsumer, listener).build(); // <5> + (request, bulkListener) -> + client.bulkAsync(request, RequestOptions.DEFAULT, bulkListener); + BulkProcessor bulkProcessor = + BulkProcessor.builder(bulkConsumer, listener).build(); // <5> // end::bulk-processor-init assertNotNull(bulkProcessor); @@ -1492,7 +1519,8 @@ public void afterBulk(long executionId, BulkRequest request, } @Override - public void afterBulk(long executionId, BulkRequest request, Throwable failure) { + public void afterBulk(long executionId, BulkRequest request, + Throwable failure) { logger.error("Failed to execute bulk", failure); // <3> } }; @@ -1500,8 +1528,10 @@ public void afterBulk(long executionId, BulkRequest request, Throwable failure) // tag::bulk-processor-options BiConsumer> bulkConsumer = - (request, bulkListener) -> highLevelClient().bulkAsync(request, RequestOptions.DEFAULT, bulkListener); - BulkProcessor.Builder builder = BulkProcessor.builder(bulkConsumer, listener); + (request, bulkListener) -> + client.bulkAsync(request, RequestOptions.DEFAULT, bulkListener); + BulkProcessor.Builder builder = + BulkProcessor.builder(bulkConsumer, listener); builder.setBulkActions(500); // <1> builder.setBulkSize(new ByteSizeValue(1L, ByteSizeUnit.MB)); // <2> builder.setConcurrentRequests(0); // <3> @@ -1568,7 +1598,8 @@ public void testTermVectors() throws Exception { request.setFields("user"); // tag::term-vectors-execute - TermVectorsResponse response = client.termvectors(request, RequestOptions.DEFAULT); + TermVectorsResponse response = + client.termvectors(request, RequestOptions.DEFAULT); // end::term-vectors-execute @@ -1579,16 +1610,17 @@ public void testTermVectors() throws Exception { boolean found = response.getFound(); // <4> // end::term-vectors-response - // tag::term-vectors-term-vectors if (response.getTermVectorsList() != null) { - List tvList = response.getTermVectorsList(); - for (TermVectorsResponse.TermVector tv : tvList) { + // tag::term-vectors-term-vectors + for (TermVectorsResponse.TermVector tv : response.getTermVectorsList()) { String fieldname = tv.getFieldName(); // <1> int docCount = tv.getFieldStatistics().getDocCount(); // <2> - long sumTotalTermFreq = tv.getFieldStatistics().getSumTotalTermFreq(); // <3> + long sumTotalTermFreq = + tv.getFieldStatistics().getSumTotalTermFreq(); // <3> long sumDocFreq = tv.getFieldStatistics().getSumDocFreq(); // <4> if (tv.getTerms() != null) { - List terms = tv.getTerms(); // <5> + List terms = + tv.getTerms(); // <5> for (TermVectorsResponse.TermVector.Term term : terms) { String termStr = term.getTerm(); // <6> int termFreq = term.getTermFreq(); // <7> @@ -1596,7 +1628,8 @@ public void testTermVectors() throws Exception { long totalTermFreq = term.getTotalTermFreq(); // <9> float score = term.getScore(); // <10> if (term.getTokens() != null) { - List tokens = term.getTokens(); // <11> + List tokens = + term.getTokens(); // <11> for (TermVectorsResponse.TermVector.Token token : tokens) { int position = token.getPosition(); // <12> int startOffset = token.getStartOffset(); // <13> @@ -1607,11 +1640,12 @@ public void testTermVectors() throws Exception { } } } + // end::term-vectors-term-vectors } - // end::term-vectors-term-vectors + ActionListener listener; // tag::term-vectors-execute-listener - ActionListener listener = new ActionListener() { + listener = new ActionListener() { @Override public void onResponse(TermVectorsResponse termVectorsResponse) { // <1> @@ -1668,7 +1702,7 @@ public void testMultiGet() throws Exception { "index", // <1> "type", // <2> "example_id")); // <3> - request.add(new MultiGetRequest.Item("index", "type", "another_id")); // <4> + request.add(new MultiGetRequest.Item("index", "type", "another_id")); // <4> // end::multi-get-request // Add a missing index so we can test it. @@ -1724,8 +1758,9 @@ public void testMultiGet() throws Exception { containsString("reason=no such index")); // <5> // end::multi-get-indexnotfound + ActionListener listener; // tag::multi-get-execute-listener - ActionListener listener = new ActionListener() { + listener = new ActionListener() { @Override public void onResponse(MultiGetResponse response) { // <1> diff --git a/docs/java-rest/high-level/document/bulk.asciidoc b/docs/java-rest/high-level/document/bulk.asciidoc index 8f0b890dda1e7..db9a3463135e8 100644 --- a/docs/java-rest/high-level/document/bulk.asciidoc +++ b/docs/java-rest/high-level/document/bulk.asciidoc @@ -1,38 +1,45 @@ -[[java-rest-high-document-bulk]] +-- +:api: bulk +:request: BulkRequest +:response: BulkResponse +-- + +[id="{upid}-{api}"] === Bulk API -NOTE: The Java High Level REST Client provides the <> to assist with bulk requests +NOTE: The Java High Level REST Client provides the +<<{upid}-{api}-processor>> to assist with bulk requests. -[[java-rest-high-document-bulk-request]] +[id="{upid}-{api}-request"] ==== Bulk Request -A `BulkRequest` can be used to execute multiple index, update and/or delete +A +{request}+ 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] +include-tagged::{doc-tests-file}[{api}-request] -------------------------------------------------- -<1> Creates the `BulkRequest` -<2> Adds a first `IndexRequest` to the Bulk request. See <> -for more information on how to build `IndexRequest`. +<1> Creates the +{request}+ +<2> Adds a first `IndexRequest` to the Bulk request. See <<{upid}-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. +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`: +And different operation types can be added to the same +{request}+: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-request-with-mixed-operations] +include-tagged::{doc-tests-file}[{api}-request-with-mixed-operations] -------------------------------------------------- -<1> Adds a `DeleteRequest` to the `BulkRequest`. See <> +<1> Adds a `DeleteRequest` to the `BulkRequest`. See <<{upid}-delete>> for more information on how to build `DeleteRequest`. -<2> Adds an `UpdateRequest` to the `BulkRequest`. See <> +<2> Adds an `UpdateRequest` to the `BulkRequest`. See <<{upid}-update>> for more information on how to build `UpdateRequest`. <3> Adds an `IndexRequest` using the SMILE format @@ -41,102 +48,66 @@ The following arguments can optionally be provided: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-request-timeout] +include-tagged::{doc-tests-file}[{api}-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] +include-tagged::{doc-tests-file}[{api}-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] +include-tagged::{doc-tests-file}[{api}-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 +<2> Number of shard copies provided as a `ActiveShardCount`: can be +`ActiveShardCount.ALL`, `ActiveShardCount.ONE` or +`ActiveShardCount.DEFAULT` (default) -The asynchronous execution of a bulk request requires both the `BulkRequest` -instance and an `ActionListener` instance to be passed to the asynchronous -method: +include::../execution.asciidoc[] -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-execute-async] --------------------------------------------------- -<1> The `BulkRequest` to execute and the `ActionListener` to use when -the execution completes - -The asynchronous method does not block and returns immediately. Once it is -completed the `ActionListener` is called back using the `onResponse` method -if the execution successfully completed or using the `onFailure` method if -it failed. - -A typical listener for `BulkResponse` looks like: - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-execute-listener] --------------------------------------------------- -<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]] +[id="{upid}-{api}-response"] ==== Bulk Response -The returned `BulkResponse` contains information about the executed operations and +The returned +{response}+ 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] +include-tagged::{doc-tests-file}[{api}-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 +<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: +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] +include-tagged::{doc-tests-file}[{api}-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: +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] +include-tagged::{doc-tests-file}[{api}-errors] -------------------------------------------------- <1> Indicate if a given operation failed <2> Retrieve the failure of the failed operation -[[java-rest-high-document-bulk-processor]] +[id="{upid}-{api}-processor"] ==== Bulk Processor The `BulkProcessor` simplifies the usage of the Bulk API by providing @@ -146,29 +117,30 @@ transparently executed as they are added to the processor. In order to execute the requests, the `BulkProcessor` requires the following components: -`RestHighLevelClient`:: This client is used to execute the `BulkRequest` +`RestHighLevelClient`:: This client is used to execute the +{request}+ and to retrieve the `BulkResponse` `BulkProcessor.Listener`:: This listener is called before and after -every `BulkRequest` execution or when a `BulkRequest` failed +every +{request}+ execution or when a +{request}+ failed -Then the `BulkProcessor.builder` method can be used to build a new `BulkProcessor`: +Then the `BulkProcessor.builder` method can be used to build a new +`BulkProcessor`: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-processor-init] +include-tagged::{doc-tests-file}[{api}-processor-init] -------------------------------------------------- <1> Create the `BulkProcessor.Listener` -<2> This method is called before each execution of a `BulkRequest` -<3> This method is called after each execution of a `BulkRequest` -<4> This method is called when a `BulkRequest` failed +<2> This method is called before each execution of a +{request}+ +<3> This method is called after each execution of a +{request}+ +<4> This method is called when a +{request}+ failed <5> Create the `BulkProcessor` by calling the `build()` method from the `BulkProcessor.Builder`. The `RestHighLevelClient.bulkAsync()` -method will be used to execute the `BulkRequest` under the hood. +method will be used to execute the +{request}+ under the hood. -The `BulkProcessor.Builder` provides methods to configure how the `BulkProcessor` -should handle requests execution: +The `BulkProcessor.Builder` provides methods to configure how the +`BulkProcessor` should handle requests execution: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-processor-options] +include-tagged::{doc-tests-file}[{api}-processor-options] -------------------------------------------------- <1> Set when to flush a new bulk request based on the number of actions currently added (defaults to 1000, use -1 to disable it) @@ -186,32 +158,32 @@ for more options. Once the `BulkProcessor` is created requests can be added to it: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-processor-add] +include-tagged::{doc-tests-file}[{api}-processor-add] -------------------------------------------------- The requests will be executed by the `BulkProcessor`, which takes care of calling the `BulkProcessor.Listener` for every bulk request. -The listener provides methods to access to the `BulkRequest` and the `BulkResponse`: +The listener provides methods to access to the +{request}+ and the +{response}+: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-processor-listener] +include-tagged::{doc-tests-file}[{api}-processor-listener] -------------------------------------------------- -<1> Called before each execution of a `BulkRequest`, this method allows -to know the number of operations that are going to be executed within the `BulkRequest` -<2> Called after each execution of a `BulkRequest`, this method allows -to know if the `BulkResponse` contains errors -<3> Called if the `BulkRequest` failed, this method allows to know +<1> Called before each execution of a +{request}+, this method allows to know +the number of operations that are going to be executed within the +{request}+ +<2> Called after each execution of a +{request}+, this method allows to know if +the +{response}+ contains errors +<3> Called if the +{request}+ failed, this method allows to know the failure Once all requests have been added to the `BulkProcessor`, its instance needs to be closed using one of the two available closing methods. -The `awaitClose()` method can be used to wait until all requests have been processed - or the specified waiting time elapses: +The `awaitClose()` method can be used to wait until all requests have been +processed or the specified waiting time elapses: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-processor-await] +include-tagged::{doc-tests-file}[{api}-processor-await] -------------------------------------------------- <1> The method returns `true` if all bulk requests completed and `false` if the waiting time elapsed before all the bulk requests completed @@ -219,9 +191,8 @@ waiting time elapsed before all the bulk requests completed The `close()` method can be used to immediately close the `BulkProcessor`: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-processor-close] +include-tagged::{doc-tests-file}[{api}-processor-close] -------------------------------------------------- -Both methods flush the requests added to the processor before closing the processor -and also forbid any new request to be added to it. - +Both methods flush the requests added to the processor before closing the +processor and also forbid any new request to be added to it. diff --git a/docs/java-rest/high-level/document/delete-by-query.asciidoc b/docs/java-rest/high-level/document/delete-by-query.asciidoc index 3a4c8a15deae6..37be8e2f3f4c8 100644 --- a/docs/java-rest/high-level/document/delete-by-query.asciidoc +++ b/docs/java-rest/high-level/document/delete-by-query.asciidoc @@ -1,26 +1,33 @@ -[[java-rest-high-document-delete-by-query]] +-- +:api: delete-by-query +:request: DeleteByQueryRequest +:response: DeleteByQueryResponse +-- + +[id="{upid}-{api}"] === Delete By Query API -[[java-rest-high-document-delete-by-query-request]] +[id="{upid}-{api}-request"] ==== Delete By Query Request -A `DeleteByQueryRequest` can be used to delete documents from an index. It requires an existing index (or a set of indices) -on which deletion is to be performed. +A +{request}+ can be used to delete documents from an index. It requires an +existing index (or a set of indices) on which deletion is to be performed. -The simplest form of a `DeleteByQueryRequest` looks like: +The simplest form of a +{request}+ looks like this and deletes all documents +in an index: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-request] +include-tagged::{doc-tests-file}[{api}-request] -------------------------------------------------- -<1> Creates the `DeleteByQueryRequest` on a set of indices. +<1> Creates the +{request}+ on a set of indices. -By default version conflicts abort the `DeleteByQueryRequest` process but you can just count them by settings it to -`proceed` in the request body +By default version conflicts abort the +{request}+ process but you can just +count them with this: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-request-conflicts] +include-tagged::{doc-tests-file}[{api}-request-conflicts] -------------------------------------------------- <1> Set `proceed` on version conflict @@ -28,7 +35,7 @@ You can limit the documents by adding a query. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-request-query] +include-tagged::{doc-tests-file}[{api}-request-query] -------------------------------------------------- <1> Only copy documents which have field `user` set to `kimchy` @@ -36,32 +43,33 @@ It’s also possible to limit the number of processed documents by setting size. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-request-size] +include-tagged::{doc-tests-file}[{api}-request-size] -------------------------------------------------- <1> Only copy 10 documents -By default `DeleteByQueryRequest` uses batches of 1000. You can change the batch size with `setBatchSize`. +By default +{request}+ uses batches of 1000. You can change the batch size +with `setBatchSize`. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-request-scrollSize] +include-tagged::{doc-tests-file}[{api}-request-scrollSize] -------------------------------------------------- <1> Use batches of 100 documents -`DeleteByQueryRequest` also helps in automatically parallelizing using `sliced-scroll` to -slice on `_uid`. Use `setSlices` to specify the number of slices to use. ++{request}+ can also be parallelized using `sliced-scroll` with `setSlices`: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-request-slices] +include-tagged::{doc-tests-file}[{api}-request-slices] -------------------------------------------------- <1> set number of slices to use -`DeleteByQueryRequest` uses the `scroll` parameter to control how long it keeps the "search context" alive. ++{request}+ uses the `scroll` parameter to control how long it keeps the +"search context" alive. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-request-scroll] +include-tagged::{doc-tests-file}[{api}-request-scroll] -------------------------------------------------- <1> set scroll time @@ -70,7 +78,7 @@ that routing value. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-request-routing] +include-tagged::{doc-tests-file}[{api}-request-routing] -------------------------------------------------- <1> set routing @@ -80,72 +88,33 @@ In addition to the options above the following arguments can optionally be also ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-request-timeout] +include-tagged::{doc-tests-file}[{api}-request-timeout] -------------------------------------------------- <1> Timeout to wait for the delete by query request to be performed as a `TimeValue` ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-request-refresh] +include-tagged::{doc-tests-file}[{api}-request-refresh] -------------------------------------------------- <1> Refresh index after calling delete by query ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-request-indicesOptions] +include-tagged::{doc-tests-file}[{api}-request-indicesOptions] -------------------------------------------------- <1> Set indices options +include::../execution.asciidoc[] -[[java-rest-high-document-delete-by-query-sync]] -==== Synchronous Execution - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-execute] --------------------------------------------------- - -[[java-rest-high-document-delete-by-query-async]] -==== Asynchronous Execution - -The asynchronous execution of an delete by query request requires both the `DeleteByQueryRequest` -instance and an `ActionListener` instance to be passed to the asynchronous -method: - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-execute-async] --------------------------------------------------- -<1> The `DeleteByQueryRequest` to execute and the `ActionListener` to use when -the execution completes - -The asynchronous method does not block and returns immediately. Once it is -completed the `ActionListener` is called back using the `onResponse` method -if the execution successfully completed or using the `onFailure` method if -it failed. - -A typical listener for `BulkByScrollResponse` looks like: - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-by-query-execute-listener] --------------------------------------------------- -<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 `DeleteByQueryRequest` fails. In this case the raised -exception is provided as an argument and no operation has been executed. - -[[java-rest-high-document-delete-by-query-execute-listener-response]] +[id="{upid}-{api}-response"] ==== Delete By Query Response -The returned `BulkByScrollResponse` contains information about the executed operations and - allows to iterate over each result as follows: +The returned +{response}+ 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[delete-by-query-response] +include-tagged::{doc-tests-file}[{api}-response] -------------------------------------------------- <1> Get total time taken <2> Check if the request timed out diff --git a/docs/java-rest/high-level/document/multi-get.asciidoc b/docs/java-rest/high-level/document/multi-get.asciidoc index 1f4628e149c96..0b9afe5962fd1 100644 --- a/docs/java-rest/high-level/document/multi-get.asciidoc +++ b/docs/java-rest/high-level/document/multi-get.asciidoc @@ -1,18 +1,24 @@ -[[java-rest-high-document-multi-get]] +-- +:api: multi-get +:request: MultiGetRequest +:response: MultiGetResponse +-- + +[id="{upid}-{api}"] === Multi-Get API The `multiGet` API executes multiple <> requests in a single http request in parallel. -[[java-rest-high-document-mulit-get-request]] +[id="{upid}-{api}-request"] ==== Multi-Get Request -A `MultiGetRequest` is built empty and you add `MultiGetRequest.Item`s to -configure what to fetch: +A +{request}+ is built empty and you add `MultiGetRequest.Item`s to configure +what to fetch: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-request] +include-tagged::{doc-tests-file}[{api}-request] -------------------------------------------------- <1> Index <2> Type @@ -27,25 +33,25 @@ You can set most of these on the `Item`: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-request-no-source] +include-tagged::{doc-tests-file}[{api}-request-no-source] -------------------------------------------------- <1> Disable source retrieval, enabled by default ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-request-source-include] +include-tagged::{doc-tests-file}[{api}-request-source-include] -------------------------------------------------- <1> Configure source inclusion for specific fields ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-request-source-exclude] +include-tagged::{doc-tests-file}[{api}-request-source-exclude] -------------------------------------------------- <1> Configure source exclusion for specific fields ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-request-stored] +include-tagged::{doc-tests-file}[{api}-request-stored] -------------------------------------------------- <1> Configure retrieval for specific stored fields (requires fields to be stored separately in the mappings) @@ -54,7 +60,7 @@ separately in the mappings) ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-request-item-extras] +include-tagged::{doc-tests-file}[{api}-request-item-extras] -------------------------------------------------- <1> Routing value <2> Parent value @@ -69,56 +75,18 @@ not on any items: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-request-top-level-extras] +include-tagged::{doc-tests-file}[{api}-request-top-level-extras] -------------------------------------------------- <1> Preference value <2> Set realtime flag to `false` (`true` by default) <3> Perform a refresh before retrieving the document (`false` by default) -[[java-rest-high-document-multi-get-sync]] -==== Synchronous Execution - -After building the `MultiGetRequest` you can execute it synchronously with -`multiGet`: - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-execute] --------------------------------------------------- - -[[java-rest-high-document-multi-get-async]] -==== Asynchronous Execution - -The asynchronous execution of a multi get request requires both the -`MultiGetRequest` instance and an `ActionListener` instance to be passed to -the asynchronous method: - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-execute-async] --------------------------------------------------- -<1> The `MultiGetRequest` to execute and the `ActionListener` to use when -the execution completes. - -The asynchronous method does not block and returns immediately. Once the -request completed the `ActionListener` is called back using the `onResponse` -method if the execution successfully completed or using the `onFailure` method -if it failed. - -A typical listener for `MultiGetResponse` looks like: - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-execute-listener] --------------------------------------------------- -<1> Called when the execution is successfully completed. The response is -provided as an argument. -<2> Called in case of failure. The raised exception is provided as an argument. +include::../execution.asciidoc[] -[[java-rest-high-document-multi-get-response]] +[id="{upid}-{api}-response"] ==== Multi Get Response -The returned `MultiGetResponse` contains a list of `MultiGetItemResponse`s in +The returned +{response}+ contains a list of `MultiGetItemResponse`s in `getResponses` in the same order that they were requested. `MultiGetItemResponse` contains *either* a <> if the get succeeded @@ -127,7 +95,7 @@ normal `GetResponse`. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-response] +include-tagged::{doc-tests-file}[{api}-response] -------------------------------------------------- <1> `getFailure` returns null because there isn't a failure. <2> `getResponse` returns the `GetResponse`. @@ -144,7 +112,7 @@ When one of the subrequests as performed against an index that does not exist ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-indexnotfound] +include-tagged::{doc-tests-file}[{api}-indexnotfound] -------------------------------------------------- <1> `getResponse` is null. <2> `getFailure` isn't and contains an `Exception`. @@ -158,7 +126,7 @@ document has a different version number, a version conflict is raised: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[multi-get-conflict] +include-tagged::{doc-tests-file}[{api}-conflict] -------------------------------------------------- <1> `getResponse` is null. <2> `getFailure` isn't and contains an `Exception`. diff --git a/docs/java-rest/high-level/document/reindex.asciidoc b/docs/java-rest/high-level/document/reindex.asciidoc index b6d98b42dc509..2482467410c96 100644 --- a/docs/java-rest/high-level/document/reindex.asciidoc +++ b/docs/java-rest/high-level/document/reindex.asciidoc @@ -1,22 +1,29 @@ -[[java-rest-high-document-reindex]] +-- +:api: reindex +:request: ReindexRequest +:response: BulkByScrollResponse +-- + +[id="{upid}-{api}"] === Reindex API -[[java-rest-high-document-reindex-request]] +[id="{upid}-{api}-request"] ==== Reindex Request -A `ReindexRequest` can be used to copy documents from one or more indexes into a destination index. +A +{request} can be used to copy documents from one or more indexes into a +destination index. It requires an existing source index and a target index which may or may not exist pre-request. Reindex does not attempt to set up the destination index. It does not copy the settings of the source index. You should set up the destination index prior to running a _reindex action, including setting up mappings, shard counts, replicas, etc. -The simplest form of a `ReindexRequest` looks like follows: +The simplest form of a +{request}+ looks like this: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[reindex-request] +include-tagged::{doc-tests-file}[{api}-request] -------------------------------------------------- -<1> Creates the `ReindexRequest` +<1> Creates the +{request}+ <2> Adds a list of sources to copy from <3> Adds the destination index @@ -28,7 +35,7 @@ source index. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[reindex-request-versionType] +include-tagged::{doc-tests-file}[{api}-request-versionType] -------------------------------------------------- <1> Set the versionType to `EXTERNAL` @@ -37,16 +44,16 @@ documents will cause a version conflict. The default `opType` is `index`. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[reindex-request-opType] +include-tagged::{doc-tests-file}[{api}-request-opType] -------------------------------------------------- <1> Set the opType to `create` -By default version conflicts abort the `_reindex` process but you can just count them by settings it to `proceed` -in the request body +By default version conflicts abort the `_reindex` process but you can just count +them instead with: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[reindex-request-conflicts] +include-tagged::{doc-tests-file}[{api}-request-conflicts] -------------------------------------------------- <1> Set `proceed` on version conflict @@ -54,7 +61,7 @@ You can limit the documents by adding a type to the source or by adding a query. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[reindex-request-typeOrQuery] +include-tagged::{doc-tests-file}[{api}-request-typeOrQuery] -------------------------------------------------- <1> Only copy `doc` type <2> Only copy documents which have field `user` set to `kimchy` @@ -63,7 +70,7 @@ It’s also possible to limit the number of processed documents by setting size. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[reindex-request-size] +include-tagged::{doc-tests-file}[{api}-request-size] -------------------------------------------------- <1> Only copy 10 documents @@ -71,7 +78,7 @@ By default `_reindex` uses batches of 1000. You can change the batch size with ` ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[reindex-request-sourceSize] +include-tagged::{doc-tests-file}[{api}-request-sourceSize] -------------------------------------------------- <1> Use batches of 100 documents @@ -79,7 +86,7 @@ Reindex can also use the ingest feature by specifying a `pipeline`. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[reindex-request-pipeline] +include-tagged::{doc-tests-file}[{api}-request-pipeline] -------------------------------------------------- <1> set pipeline to `my_pipeline` @@ -88,21 +95,21 @@ selective query to size and sort. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[reindex-request-sort] +include-tagged::{doc-tests-file}[{api}-request-sort] -------------------------------------------------- <1> add descending sort to`field1` <2> add ascending sort to `field2` -`ReindexRequest` also supports a `script` that modifies the document. It allows you to also change the document's -metadata. The following example illustrates that. ++{request} also supports a `script` that modifies the document. It allows you to +also change the document's metadata. The following example illustrates that. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[reindex-request-script] +include-tagged::{doc-tests-file}[{api}-request-script] -------------------------------------------------- <1> `setScript` to increment the `likes` field on all documents with user `kimchy`. -`ReindexRequest` supports reindexing from a remote Elasticsearch cluster. When using a remote cluster the query should be ++{request}+ supports reindexing from a remote Elasticsearch cluster. When using a remote cluster the query should be specified inside the `RemoteInfo` object and not using `setSourceQuery`. If both the remote info and the source query are set it results in a validation error during the request. The reason for this is that the remote Elasticsearch may not understand queries built by the modern query builders. The remote cluster support works all the way back to Elasticsearch @@ -111,23 +118,24 @@ in JSON. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[reindex-request-remote] +include-tagged::{doc-tests-file}[{api}-request-remote] -------------------------------------------------- <1> set remote elastic cluster -`ReindexRequest` also helps in automatically parallelizing using `sliced-scroll` to ++{request}+ also helps in automatically parallelizing using `sliced-scroll` to slice on `_uid`. Use `setSlices` to specify the number of slices to use. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[reindex-request-slices] +include-tagged::{doc-tests-file}[{api}-request-slices] -------------------------------------------------- <1> set number of slices to use -`ReindexRequest` uses the `scroll` parameter to control how long it keeps the "search context" alive. ++{request}+ uses the `scroll` parameter to control how long it keeps the +"search context" alive. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[reindex-request-scroll] +include-tagged::{doc-tests-file}[{api}-request-scroll] -------------------------------------------------- <1> set scroll time @@ -137,66 +145,27 @@ In addition to the options above the following arguments can optionally be also ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[reindex-request-timeout] +include-tagged::{doc-tests-file}[{api}-request-timeout] -------------------------------------------------- <1> Timeout to wait for the reindex request to be performed as a `TimeValue` ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[reindex-request-refresh] +include-tagged::{doc-tests-file}[{api}-request-refresh] -------------------------------------------------- <1> Refresh index after calling reindex +include::../execution.asciidoc[] -[[java-rest-high-document-reindex-sync]] -==== Synchronous Execution - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[reindex-execute] --------------------------------------------------- - -[[java-rest-high-document-reindex-async]] -==== Asynchronous Execution - -The asynchronous execution of a reindex request requires both the `ReindexRequest` -instance and an `ActionListener` instance to be passed to the asynchronous -method: - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[reindex-execute-async] --------------------------------------------------- -<1> The `ReindexRequest` to execute and the `ActionListener` to use when -the execution completes - -The asynchronous method does not block and returns immediately. Once it is -completed the `ActionListener` is called back using the `onResponse` method -if the execution successfully completed or using the `onFailure` method if -it failed. - -A typical listener for `BulkByScrollResponse` looks like: - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[reindex-execute-listener] --------------------------------------------------- -<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 `ReindexRequest` fails. In this case the raised -exception is provided as an argument and no operation has been executed. - -[[java-rest-high-document-reindex-response]] +[id="{upid}-{api}-response"] ==== Reindex Response -The returned `BulkByScrollResponse` contains information about the executed operations and - allows to iterate over each result as follows: +The returned +{response}+ 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[reindex-response] +include-tagged::{doc-tests-file}[{api}-response] -------------------------------------------------- <1> Get total time taken <2> Check if the request timed out diff --git a/docs/java-rest/high-level/document/rethrottle.asciidoc b/docs/java-rest/high-level/document/rethrottle.asciidoc index 9f6fd69dbcd49..cb606521a1d52 100644 --- a/docs/java-rest/high-level/document/rethrottle.asciidoc +++ b/docs/java-rest/high-level/document/rethrottle.asciidoc @@ -1,10 +1,16 @@ -[[java-rest-high-document-rethrottle]] +-- +:api: rethrottle +:request: RethrottleRequest +:response: ListTasksResponse +-- + +[id="{upid}-{api}"] === Rethrottle API -[[java-rest-high-document-rethrottle-request]] +[id="{upid}-{api}-request"] ==== Rethrottle Request -A `RethrottleRequest` can be used to change the current throttling on a running +A +{request}+ can be used to change the current throttling on a running reindex, update-by-query or delete-by-query task or to disable throttling of the task entirely. It requires the task Id of the task to change. @@ -13,16 +19,16 @@ task using the following: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[rethrottle-disable-request] +include-tagged::{doc-tests-file}[{api}-disable-request] -------------------------------------------------- -<1> Create a `RethrottleRequest` that disables throttling for a specific task id +<1> Create a +{request}+ that disables throttling for a specific task id By providing a `requestsPerSecond` argument, the request will change the existing task throttling to the specified value: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[rethrottle-request] +include-tagged::{doc-tests-file}[{api}-request] -------------------------------------------------- <1> Request to change the throttling of a task to 100 requests per second @@ -32,22 +38,22 @@ should be rethrottled: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[rethrottle-request-execution] +include-tagged::{doc-tests-file}[{api}-request-execution] -------------------------------------------------- <1> Execute reindex rethrottling request <2> The same for update-by-query <3> The same for delete-by-query -[[java-rest-high-document-rethrottle-async]] +[id="{upid}-{api}-async"] ==== Asynchronous Execution -The asynchronous execution of a rethrottle request requires both the `RethrottleRequest` +The asynchronous execution of a rethrottle request requires both the +{request}+ instance and an `ActionListener` instance to be passed to the asynchronous method: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[rethrottle-execute-async] +include-tagged::{doc-tests-file}[{api}-execute-async] -------------------------------------------------- <1> Execute reindex rethrottling asynchronously <2> The same for update-by-query @@ -60,14 +66,14 @@ it failed. A typical listener looks like this: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[rethrottle-request-async-listener] +include-tagged::{doc-tests-file}[{api}-request-async-listener] -------------------------------------------------- <1> Code executed when the request is successfully completed <2> Code executed when the request fails with an exception -[[java-rest-high-document-retrottle-response]] +[id="{upid}-{api}-response"] ==== Rethrottle Response -Rethrottling returns the task that has been rethrottled in the form of a -`ListTasksResponse`. The structure of this response object is described in detail +Rethrottling returns the task that has been rethrottled in the form of a ++{response}+. The structure of this response object is described in detail in <>. diff --git a/docs/java-rest/high-level/document/update-by-query.asciidoc b/docs/java-rest/high-level/document/update-by-query.asciidoc index 5c7e4f5d3b072..fdf50148df4c8 100644 --- a/docs/java-rest/high-level/document/update-by-query.asciidoc +++ b/docs/java-rest/high-level/document/update-by-query.asciidoc @@ -1,27 +1,34 @@ -[[java-rest-high-document-update-by-query]] +-- +:api: update-by-query +:request: UpdateByQueryRequest +:response: UpdateByQueryResponse +-- + +[id="{upid}-{api}"] === Update By Query API -[[java-rest-high-document-update-by-query-request]] +[id="{upid}-{api}-request"] ==== Update By Query Request -A `UpdateByQueryRequest` can be used to update documents in an index. +A +{request}+ can be used to update documents in an index. -It requires an existing index (or a set of indices) on which the update is to be performed. +It requires an existing index (or a set of indices) on which the update is to +be performed. -The simplest form of a `UpdateByQueryRequest` looks like follows: +The simplest form of a +{request}+ looks like this: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-by-query-request] +include-tagged::{doc-tests-file}[{api}-request] -------------------------------------------------- -<1> Creates the `UpdateByQueryRequest` on a set of indices. +<1> Creates the +{request}+ on a set of indices. -By default version conflicts abort the `UpdateByQueryRequest` process but you can just count them by settings it to -`proceed` in the request body +By default version conflicts abort the +{request}+ process but you can just +count them instead with: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-by-query-request-conflicts] +include-tagged::{doc-tests-file}[{api}-request-conflicts] -------------------------------------------------- <1> Set `proceed` on version conflict @@ -29,7 +36,7 @@ You can limit the documents by adding a query. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-by-query-request-query] +include-tagged::{doc-tests-file}[{api}-request-query] -------------------------------------------------- <1> Only copy documents which have field `user` set to `kimchy` @@ -37,15 +44,16 @@ It’s also possible to limit the number of processed documents by setting size. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-by-query-request-size] +include-tagged::{doc-tests-file}[{api}-request-size] -------------------------------------------------- <1> Only copy 10 documents -By default `UpdateByQueryRequest` uses batches of 1000. You can change the batch size with `setBatchSize`. +By default +{request}+ uses batches of 1000. You can change the batch size with +`setBatchSize`. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-by-query-request-scrollSize] +include-tagged::{doc-tests-file}[{api}-request-scrollSize] -------------------------------------------------- <1> Use batches of 100 documents @@ -53,24 +61,23 @@ Update by query can also use the ingest feature by specifying a `pipeline`. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-by-query-request-pipeline] +include-tagged::{doc-tests-file}[{api}-request-pipeline] -------------------------------------------------- <1> set pipeline to `my_pipeline` -`UpdateByQueryRequest` also supports a `script` that modifies the document. The following example illustrates that. ++{request}+ also supports a `script` that modifies the document: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-by-query-request-script] +include-tagged::{doc-tests-file}[{api}-request-script] -------------------------------------------------- <1> `setScript` to increment the `likes` field on all documents with user `kimchy`. -`UpdateByQueryRequest` also helps in automatically parallelizing using `sliced-scroll` to -slice on `_uid`. Use `setSlices` to specify the number of slices to use. ++{request}+ can be parallelized using `sliced-scroll` with `setSlices`: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-by-query-request-slices] +include-tagged::{doc-tests-file}[{api}-request-slices] -------------------------------------------------- <1> set number of slices to use @@ -78,7 +85,7 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-by-query-request-sli ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-by-query-request-scroll] +include-tagged::{doc-tests-file}[{api}-request-scroll] -------------------------------------------------- <1> set scroll time @@ -87,7 +94,7 @@ that routing value. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-by-query-request-routing] +include-tagged::{doc-tests-file}[{api}-request-routing] -------------------------------------------------- <1> set routing @@ -97,72 +104,33 @@ In addition to the options above the following arguments can optionally be also ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-by-query-request-timeout] +include-tagged::{doc-tests-file}[{api}-request-timeout] -------------------------------------------------- <1> Timeout to wait for the update by query request to be performed as a `TimeValue` ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-by-query-request-refresh] +include-tagged::{doc-tests-file}[{api}-request-refresh] -------------------------------------------------- <1> Refresh index after calling update by query ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-by-query-request-indicesOptions] +include-tagged::{doc-tests-file}[{api}-request-indicesOptions] -------------------------------------------------- <1> Set indices options +include::../execution.asciidoc[] -[[java-rest-high-document-update-by-query-sync]] -==== Synchronous Execution - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-by-query-execute] --------------------------------------------------- - -[[java-rest-high-document-update-by-query-async]] -==== Asynchronous Execution - -The asynchronous execution of an update by query request requires both the `UpdateByQueryRequest` -instance and an `ActionListener` instance to be passed to the asynchronous -method: - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-by-query-execute-async] --------------------------------------------------- -<1> The `UpdateByQueryRequest` to execute and the `ActionListener` to use when -the execution completes - -The asynchronous method does not block and returns immediately. Once it is -completed the `ActionListener` is called back using the `onResponse` method -if the execution successfully completed or using the `onFailure` method if -it failed. - -A typical listener for `BulkByScrollResponse` looks like: - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-by-query-execute-listener] --------------------------------------------------- -<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 `UpdateByQueryRequest` fails. In this case the raised -exception is provided as an argument and no operation has been executed. - -[[java-rest-high-document-update-by-query-execute-listener-response]] +[id="{upid}-{api}-response"] ==== Update By Query Response -The returned `BulkByScrollResponse` contains information about the executed operations and - allows to iterate over each result as follows: +The returned +{resposne}+ 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[update-by-query-response] +include-tagged::{doc-tests-file}[{api}-response] -------------------------------------------------- <1> Get total time taken <2> Check if the request timed out