Update API
editUpdate API
editUpdate Request
editAn UpdateRequest
requires the following arguments:
The Update API allows to update an existing document by using a script or by passing a partial document.
Updates with a script
editThe script can be provided as an inline script:
Map<String, Object> parameters = singletonMap("count", 4); Script inline = new Script(ScriptType.INLINE, "painless", "ctx._source.field += params.count", parameters); request.script(inline);
Script parameters provided as a |
|
Create an inline script using the |
|
Sets the script to the update request |
Or as a stored script:
Updates with a partial document
editWhen using updates with a partial document, the partial document will be merged with the existing document.
The partial document can be provided in different ways:
UpdateRequest request = new UpdateRequest("posts", "doc", "1"); String jsonString = "{" + "\"updated\":\"2017-01-01\"," + "\"reason\":\"daily update\"" + "}"; request.doc(jsonString, XContentType.JSON);
Map<String, Object> jsonMap = new HashMap<>(); jsonMap.put("updated", new Date()); jsonMap.put("reason", "daily update"); UpdateRequest request = new UpdateRequest("posts", "doc", "1") .doc(jsonMap);
XContentBuilder builder = XContentFactory.jsonBuilder(); builder.startObject(); { builder.field("updated", new Date()); builder.field("reason", "daily update"); } builder.endObject(); UpdateRequest request = new UpdateRequest("posts", "doc", "1") .doc(builder);
Partial document source provided as an |
Upserts
editIf the document does not already exist, it is possible to define some content that
will be inserted as a new document using the upsert
method:
Similarly to the partial document updates, the content of the upsert
document
can be defined using methods that accept String
, Map
, XContentBuilder
or
Object
key-pairs.
Optional arguments
editThe following arguments can optionally be provided:
Timeout to wait for primary shard to become available as a |
|
Timeout to wait for primary shard to become available as a |
request.setRefreshPolicy(WriteRequest.RefreshPolicy.WAIT_UNTIL); request.setRefreshPolicy("wait_for");
How many times to retry the update operation if the document to update has been changed by another operation between the get and indexing phases of the update operation |
String[] includes = new String[]{"updated", "r*"}; String[] excludes = Strings.EMPTY_ARRAY; request.fetchSource(new FetchSourceContext(true, includes, excludes));
String[] includes = Strings.EMPTY_ARRAY; String[] excludes = new String[]{"updated"}; request.fetchSource(new FetchSourceContext(true, includes, excludes));
Indicate that the script must run regardless of whether the document exists or not, ie the script takes care of creating the document if it does not already exist. |
Synchronous Execution
editUpdateResponse updateResponse = client.update(request);
Asynchronous Execution
editUpdate Response
editThe returned UpdateResponse
allows to retrieve information about the executed
operation as follows:
String index = updateResponse.getIndex(); String type = updateResponse.getType(); String id = updateResponse.getId(); long version = updateResponse.getVersion(); if (updateResponse.getResult() == DocWriteResponse.Result.CREATED) { } else if (updateResponse.getResult() == DocWriteResponse.Result.UPDATED) { } else if (updateResponse.getResult() == DocWriteResponse.Result.DELETED) { } else if (updateResponse.getResult() == DocWriteResponse.Result.NOOP) { }
Handle the case where the document was created for the first time (upsert) |
|
Handle the case where the document was updated |
|
Handle the case where the document was deleted |
|
Handle the case where the document was not impacted by the update, ie no operation (noop) was executed on the document |
When the source retrieval is enabled in the UpdateRequest
through the fetchSource method, the response contains the
source of the updated document:
GetResult result = updateResponse.getGetResult(); if (result.isExists()) { String sourceAsString = result.sourceAsString(); Map<String, Object> sourceAsMap = result.sourceAsMap(); byte[] sourceAsBytes = result.source(); } else { }
Retrieve the updated document as a |
|
Retrieve the source of the updated document as a |
|
Retrieve the source of the updated document as a |
|
Retrieve the source of the updated document as a |
|
Handle the scenario where the source of the document is not present in the response (this is the case by default) |
It is also possible to check for shard failures:
ReplicationResponse.ShardInfo shardInfo = updateResponse.getShardInfo(); if (shardInfo.getTotal() != shardInfo.getSuccessful()) { } if (shardInfo.getFailed() > 0) { for (ReplicationResponse.ShardInfo.Failure failure : shardInfo.getFailures()) { String reason = failure.reason(); } }
Handle the situation where number of successful shards is less than total shards |
|
Handle the potential failures |
When a UpdateRequest
is performed against a document that does not exist,
the response has 404
status code, an ElasticsearchException
gets thrown
which needs to be handled as follows:
UpdateRequest request = new UpdateRequest("posts", "type", "does_not_exist").doc("field", "value"); try { UpdateResponse updateResponse = client.update(request); } catch (ElasticsearchException e) { if (e.status() == RestStatus.NOT_FOUND) { } }
If there is a version conflict, an ElasticsearchException
will
be thrown: