OpenSearch/docs/java-api/update.asciidoc

[[java-update-api]]
== Update API


You can either create an `UpdateRequest` and send it to the client:

[source,java]
--------------------------------------------------
UpdateRequest updateRequest = new UpdateRequest();
updateRequest.index("index");
updateRequest.type("type");
updateRequest.id("1");
updateRequest.doc(jsonBuilder()
        .startObject()
            .field("gender", "male")
        .endObject());
client.update(updateRequest).get();
--------------------------------------------------

Or you can use `prepareUpdate()` method:

[source,java]
--------------------------------------------------
client.prepareUpdate("ttl", "doc", "1")
        .setScript(new Script("ctx._source.gender = \"male\"" <1> , ScriptService.ScriptType.INLINE, null, null))
        .get();

client.prepareUpdate("ttl", "doc", "1")
        .setDoc(jsonBuilder()               <2>
            .startObject()
                .field("gender", "male")
            .endObject())
        .get();
--------------------------------------------------
<1> Your script. It could also be a locally stored script name.
In that case, you'll need to use `ScriptService.ScriptType.FILE`
<2> Document which will be merged to the existing one.

Note that you can't provide both `script` and `doc`.

[[java-update-api-script]]
=== Update by script

The update API allows to update a document based on a script provided:

[source,java]
--------------------------------------------------
UpdateRequest updateRequest = new UpdateRequest("ttl", "doc", "1")
        .script(new Script("ctx._source.gender = \"male\""));
client.update(updateRequest).get();
--------------------------------------------------


[[java-update-api-merge-docs]]
=== Update by merging documents

The update API also support passing a partial document, which will be merged into the existing document (simple
recursive merge, inner merging of objects, replacing core "keys/values" and arrays). For example:

[source,java]
--------------------------------------------------
UpdateRequest updateRequest = new UpdateRequest("index", "type", "1")
        .doc(jsonBuilder()
            .startObject()
                .field("gender", "male")
            .endObject());
client.update(updateRequest).get();
--------------------------------------------------


[[java-update-api-upsert]]
=== Upsert

There is also support for `upsert`. If the document already exists, the content of the `upsert`
element will be used to index the fresh doc:

[source,java]
--------------------------------------------------
IndexRequest indexRequest = new IndexRequest("index", "type", "1")
        .source(jsonBuilder()
            .startObject()
                .field("name", "Joe Smith")
                .field("gender", "male")
            .endObject());
UpdateRequest updateRequest = new UpdateRequest("index", "type", "1")
        .doc(jsonBuilder()
            .startObject()
                .field("gender", "male")
            .endObject())
        .upsert(indexRequest);              <1>
client.update(updateRequest).get();
--------------------------------------------------
<1> If the document does not exist, the one in `indexRequest` will be added

If the document `index/type/1` already exists, we will have after this operation a document like:

[source,js]
--------------------------------------------------
{
    "name"  : "Joe Dalton",
    "gender": "male"        <1>
}
--------------------------------------------------
<1> This field is added by the update request

If it does not exist, we will have a new document:

[source,js]
--------------------------------------------------
{
    "name" : "Joe Smith",
    "gender": "male"
}
--------------------------------------------------