mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-30 10:23:41 -04:00
Added minimal docs for reindex api in java-api docs
Additionally: * Included the existing update by query java api docs in java-api docs. (for some reason it was never included, it needed some tweaking and then it was good to go) * moved delete-by-query / update-by-query code samples to java file so that we can verify that these samples at least compile. Closes #24203
This commit is contained in:
Martijn van Groningen
parent
4897e0034b
commit
069a876542
6 changed files with 255 additions and 117 deletions
|
|
@ -1,18 +1,13 @@
|
|||
[[docs-update-by-query]]
|
||||
== Update By Query API
|
||||
[[java-docs-update-by-query]]
|
||||
=== Update By Query API
|
||||
|
||||
The simplest usage of `updateByQuery` updates each
|
||||
document in an index without changing the source. This usage enables
|
||||
<<picking-up-a-new-property,picking up a new property>> or another online
|
||||
mapping change.
|
||||
picking up a new property or another online mapping change.
|
||||
|
||||
[source,java]
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
UpdateByQueryRequestBuilder updateByQuery = UpdateByQueryAction.INSTANCE.newRequestBuilder(client);
|
||||
|
||||
updateByQuery.source("source_index").abortOnVersionConflict(false);
|
||||
|
||||
BulkByScrollResponse response = updateByQuery.get();
|
||||
include-tagged::{client-reindex-tests}/ReindexDocumentationIT.java[update-by-query]
|
||||
--------------------------------------------------
|
||||
|
||||
Calls to the `updateByQuery` API start by getting a snapshot of the index, indexing
|
||||
|
|
@ -41,78 +36,50 @@ The `UpdateByQueryRequestBuilder` API supports filtering the updated documents,
|
|||
limiting the total number of documents to update, and updating documents
|
||||
with a script:
|
||||
|
||||
[source,java]
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
UpdateByQueryRequestBuilder updateByQuery = UpdateByQueryAction.INSTANCE.newRequestBuilder(client);
|
||||
|
||||
updateByQuery.source("source_index")
|
||||
.filter(termQuery("level", "awesome"))
|
||||
.size(1000)
|
||||
.script(new Script("ctx._source.awesome = 'absolutely'", ScriptType.INLINE, "painless", emptyMap()));
|
||||
|
||||
BulkByScrollResponse response = updateByQuery.get();
|
||||
include-tagged::{client-reindex-tests}/ReindexDocumentationIT.java[update-by-query-filter]
|
||||
--------------------------------------------------
|
||||
|
||||
`UpdateByQueryRequestBuilder` also enables direct access to the query used
|
||||
to select the documents. You can use this access to change the default scroll size or
|
||||
otherwise modify the request for matching documents.
|
||||
|
||||
[source,java]
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
UpdateByQueryRequestBuilder updateByQuery = UpdateByQueryAction.INSTANCE.newRequestBuilder(client);
|
||||
|
||||
updateByQuery.source("source_index")
|
||||
.source().setSize(500);
|
||||
|
||||
BulkByScrollResponse response = updateByQuery.get();
|
||||
include-tagged::{client-reindex-tests}/ReindexDocumentationIT.java[update-by-query-size]
|
||||
--------------------------------------------------
|
||||
|
||||
You can also combine `size` with sorting to limit the documents updated:
|
||||
|
||||
[source,java]
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
UpdateByQueryRequestBuilder updateByQuery = UpdateByQueryAction.INSTANCE.newRequestBuilder(client);
|
||||
|
||||
updateByQuery.source("source_index").size(100)
|
||||
.source().addSort("cat", SortOrder.DESC);
|
||||
|
||||
BulkByScrollResponse response = updateByQuery.get();
|
||||
include-tagged::{client-reindex-tests}/ReindexDocumentationIT.java[update-by-query-sort]
|
||||
--------------------------------------------------
|
||||
|
||||
In addition to changing the `_source` field for the document, you can use a
|
||||
script to change the action, similar to the Update API:
|
||||
|
||||
[source,java]
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
UpdateByQueryRequestBuilder updateByQuery = UpdateByQueryAction.INSTANCE.newRequestBuilder(client);
|
||||
|
||||
updateByQuery.source("source_index")
|
||||
.script(new Script(
|
||||
"if (ctx._source.awesome == 'absolutely) {"
|
||||
+ " ctx.op='noop'
|
||||
+ "} else if (ctx._source.awesome == 'lame') {"
|
||||
+ " ctx.op='delete'"
|
||||
+ "} else {"
|
||||
+ "ctx._source.awesome = 'absolutely'}", ScriptType.INLINE, "painless", emptyMap()));
|
||||
|
||||
BulkByScrollResponse response = updateByQuery.get();
|
||||
include-tagged::{client-reindex-tests}/ReindexDocumentationIT.java[update-by-query-script]
|
||||
--------------------------------------------------
|
||||
|
||||
As in the <<docs-update,Update API>>, you can set the value of `ctx.op` to change the
|
||||
As in the <<java-docs-update,Update API>>, you can set the value of `ctx.op` to change the
|
||||
operation that executes:
|
||||
|
||||
`noop`::
|
||||
|
||||
Set `ctx.op = "noop"` if your script doesn't make any
|
||||
changes. The `updateByQuery` operaton then omits that document from the updates.
|
||||
This behavior increments the `noop` counter in the
|
||||
<<docs-update-by-query-response-body, response body>>.
|
||||
This behavior increments the `noop` counter in the response body.
|
||||
|
||||
`delete`::
|
||||
|
||||
Set `ctx.op = "delete"` if your script decides that the document must be
|
||||
deleted. The deletion will be reported in the `deleted` counter in the
|
||||
<<docs-update-by-query-response-body, response body>>.
|
||||
response body.
|
||||
|
||||
Setting `ctx.op` to any other value generates an error. Setting any
|
||||
other field in `ctx` generates an error.
|
||||
|
|
@ -123,79 +90,55 @@ from its original location.
|
|||
|
||||
You can also perform these operations on multiple indices and types at once, similar to the search API:
|
||||
|
||||
[source,java]
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
UpdateByQueryRequestBuilder updateByQuery = UpdateByQueryAction.INSTANCE.newRequestBuilder(client);
|
||||
|
||||
updateByQuery.source("foo", "bar").source().setTypes("a", "b");
|
||||
|
||||
BulkByScrollResponse response = updateByQuery.get();
|
||||
include-tagged::{client-reindex-tests}/ReindexDocumentationIT.java[update-by-query-multi-index]
|
||||
--------------------------------------------------
|
||||
|
||||
If you provide a `routing` value then the process copies the routing value to the scroll query,
|
||||
limiting the process to the shards that match that routing value:
|
||||
|
||||
[source,java]
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
UpdateByQueryRequestBuilder updateByQuery = UpdateByQueryAction.INSTANCE.newRequestBuilder(client);
|
||||
|
||||
updateByQuery.source().setRouting("cat");
|
||||
|
||||
BulkByScrollResponse response = updateByQuery.get();
|
||||
include-tagged::{client-reindex-tests}/ReindexDocumentationIT.java[update-by-query-routing]
|
||||
--------------------------------------------------
|
||||
|
||||
`updateByQuery` can also use the <<ingest>> feature by
|
||||
`updateByQuery` can also use the ingest node by
|
||||
specifying a `pipeline` like this:
|
||||
|
||||
[source,java]
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
UpdateByQueryRequestBuilder updateByQuery = UpdateByQueryAction.INSTANCE.newRequestBuilder(client);
|
||||
|
||||
updateByQuery.setPipeline("hurray");
|
||||
|
||||
BulkByScrollResponse response = updateByQuery.get();
|
||||
include-tagged::{client-reindex-tests}/ReindexDocumentationIT.java[update-by-query-pipeline]
|
||||
--------------------------------------------------
|
||||
|
||||
[float]
|
||||
[[docs-update-by-query-task-api]]
|
||||
[[java-docs-update-by-query-task-api]]
|
||||
=== Works with the Task API
|
||||
|
||||
You can fetch the status of all running update-by-query requests with the
|
||||
<<tasks,Task API>>:
|
||||
You can fetch the status of all running update-by-query requests with the Task API:
|
||||
|
||||
[source,java]
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
ListTasksResponse tasksList = client.admin().cluster().prepareListTasks()
|
||||
.setActions(UpdateByQueryAction.NAME).setDetailed(true).get();
|
||||
|
||||
for (TaskInfo info: tasksList.getTasks()) {
|
||||
TaskId taskId = info.getTaskId();
|
||||
BulkByScrollTask.Status status = (BulkByScrollTask.Status) info.getStatus();
|
||||
// do stuff
|
||||
}
|
||||
|
||||
include-tagged::{client-reindex-tests}/ReindexDocumentationIT.java[update-by-query-list-tasks]
|
||||
--------------------------------------------------
|
||||
|
||||
With the `TaskId` shown above you can look up the task directly:
|
||||
|
||||
// provide API Example
|
||||
[source,java]
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
GetTaskResponse get = client.admin().cluster().prepareGetTask(taskId).get();
|
||||
include-tagged::{client-reindex-tests}/ReindexDocumentationIT.java[update-by-query-get-task]
|
||||
--------------------------------------------------
|
||||
|
||||
[float]
|
||||
[[docs-update-by-query-cancel-task-api]]
|
||||
[[java-docs-update-by-query-cancel-task-api]]
|
||||
=== Works with the Cancel Task API
|
||||
|
||||
Any Update By Query can be canceled using the <<tasks,Task Cancel API>>:
|
||||
Any Update By Query can be canceled using the Task Cancel API:
|
||||
|
||||
[source,java]
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
// Cancel all update-by-query requests
|
||||
client.admin().cluster().prepareCancelTasks().setActions(UpdateByQueryAction.NAME).get().getTasks()
|
||||
// Cancel a specific update-by-query request
|
||||
client.admin().cluster().prepareCancelTasks().setTaskId(taskId).get().getTasks()
|
||||
include-tagged::{client-reindex-tests}/ReindexDocumentationIT.java[update-by-query-cancel-task]
|
||||
--------------------------------------------------
|
||||
|
||||
Use the `list tasks` API to find the value of `taskId`.
|
||||
|
|
@ -204,14 +147,14 @@ Cancelling a request is typically a very fast process but can take up to a few s
|
|||
The task status API continues to list the task until the cancellation is complete.
|
||||
|
||||
[float]
|
||||
[[docs-update-by-query-rethrottle]]
|
||||
[[java-docs-update-by-query-rethrottle]]
|
||||
=== Rethrottling
|
||||
|
||||
Use the `_rethrottle` API to change the value of `requests_per_second` on a running update:
|
||||
|
||||
[source,java]
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
RethrottleAction.INSTANCE.newRequestBuilder(client).setTaskId(taskId).setRequestsPerSecond(2.0f).get();
|
||||
include-tagged::{client-reindex-tests}/ReindexDocumentationIT.java[update-by-query-rethrottle]
|
||||
--------------------------------------------------
|
||||
|
||||
Use the `list tasks` API to find the value of `taskId`.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue