[[java-docs-update]]
=== 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("_doc");
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>
            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 `ScriptType.FILE`.
<2> Document which will be merged to the existing one.

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

[[java-docs-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-docs-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-docs-update-api-upsert]]
==== Upsert

There is also support for `upsert`. If the document does not exist, 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("name", "Joe Dalton")
            .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/_doc/1` already exists, we will have after this operation a document like:

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

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

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