Elasticsearch Update API

The update API allows to update a document based on a script provided. The operation gets the document (collocated with the shard) from the index, runs the script (with optional script language and parameters), and index back the result (also allows to delete, or ignore the operation). It uses versioning to make sure no updates have happened during the “get” and “reindex”.

Note, this operation still means full reindex of the document, it just removes some network roundtrips and reduces chances of version conflicts between the get and the index. The _source field needs to be enabled for this feature to work.

Elasticsearch update API - Table Of contents

• Scripted updates
• Updates with a partial document
• Detecting noop updates
• Updating Documents
• Update by merging documents
• Upserts
• scripted_upsert
• Parameters

For example, lets index a simple doc:

curl -XPUT localhost:9200/test/type1/1 -d '{
    "counter" : 1,
    "tags" : ["red"]
}'

Scripted Updates

Now, we can execute a script that would increment the counter:

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
    "script" : {
        "inline": "ctx._source.counter += count",
        "params" : {
            "count" : 4
        }
    }
}'

We can add a tag to the list of tags (note, if the tag exists, it will still add it, since its a list):

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
    "script" : {
        "inline": "ctx._source.tags += tag",
        "params" : {
            "tag" : "blue"
        }
    }
}'

In addition to _source, the following variables are available through the ctx map: _index, _type, _id, _version, _routing, _parent, _timestamp, _ttl.

Learn how to use Elasticsearch, from beginner basics to advanced techniques, with online video tutorials taught by industry experts. Enroll Our Elasticsearch Online Training Today!

We can also add a new field to the document:

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
    "script" : "ctx._source.name_of_new_field = "value_of_new_field""

}'

Or remove a field from the document:

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
    "script" : "ctx._source.remove("name_of_field")"
}'

And, we can even change the operation that is executed. This example deletes the doc if the tags field contain blue, otherwise it does nothing (noop):

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
    "script" : {
        "inline": "ctx._source.tags.contains(tag) ? ctx.op = "delete" : ctx.op = "none"",
        "params" : {
            "tag" : "blue"
        }
    }
}'

Updates with a Partial Document

The update API also supports 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:

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
    "doc" : {
        "name" : "new_name"
    }
}'

If both doc and script are specified, then doc is ignored. Best is to put your field pairs of the partial document in the script itself.

Detecting noop Updates

If doc is specified, its value is merged with the existing _source. By default, the document is only reindexed if the new _source field differs from the old. Setting detect_noop to false will cause Elasticsearch to always update the document, even if it hasn’t changed. For example:

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
    "doc" : {
        "name" : "new_name"
    },
    "detect_noop": false
}'

If name was new_name before the request was sent then document is still reindexed.

Check Out: "ElasticSeaarch Interview Questions"

Updating Documents

In addition to being able to index and replace documents, we can also update documents. Note that Elasticsearch does not actually do in-place updates under the hood. Whenever we do an update, Elasticsearch deletes the old document and then indexes a new document with the update applied to it in one shot.

This example shows how to update our previous document (ID of 1) by changing the name field to “Jane Doe”:

curl -XPOST 'localhost:9200/customer/external/1/_update?pretty' -d '
{
  "doc": { "name": "Jane Doe" }
}'

This example shows how to update our previous document (ID of 1) by changing the name field to “Jane Doe” and at the same time add an age field to it:

curl -XPOST 'localhost:9200/customer/external/1/_update?pretty' -d '  

{
  "doc": { "name": "Jane Doe", "age": 20 }
}'

Updates can also be performed by using simple scripts. Note that dynamic scripts like the following are disabled by default. This example uses a script to increment the age by 5:

curl -XPOST 'localhost:9200/customer/external/1/_update?pretty' -d ' { "script" : "ctx._source.age += 5" }'

In the above example, ctx._source refers to the current source document that is about to be updated.

Note that as of this writing, updates can only be performed on a single document at a time. In the future, Elasticsearch might provide the ability to update multiple documents given a query condition (like an SQL UPDATE-WHERE statement).

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:

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

Related Page: "The Bulk API | Elasticsearch"

Upserts

If the document does not already exist, the contents of the upsert element will be inserted as a new document. If the document does exist, then the script will be executed instead:

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
    "script" : {
        "inline": "ctx._source.counter += count",
        "params" : {
            "count" : 4
        }
    },
    "upsert" : {
        "counter" : 1
    }
}'

scripted_upsert

If you would like your script to run regardless of whether the document exists or not — i.e. the script handles initializing the document instead of the upsert element — then set scripted_upsert to true:

curl -XPOST 'localhost:9200/sessions/session/dh3sgudg8gsrgl/_update' -d '{     
 "scripted_upsert":true,
    "script" : {
        "id": "my_web_session_summariser",
        "params" : {
            "pageViewEvent" : {
                "url":"foo.com/bar",
                "response":404,
                "time":"2014-01-01 12:32"
            }
        }
    },
    "upsert" : {}
}'

doc_as_upsertEDIT

Instead of sending a partial doc plus an upsert doc, setting doc_as_upsert to true will use the contents of doc as the upsert value:

curl -XPOST 'localhost:9200/test/type1/1/_update' -d '{
    "doc" : {
        "name" : "new_name"
    },
    "doc_as_upsert" : true
}'

Parameters

The update operation supports the following query-string parameters:

retry_on_conflict	In between the get and indexing phases of the update, it is possible that another process might have already updated the same document. By default, the update will fail with a version conflict exception. The retry_on_conflict parameter controls how many times to retry the update before finally throwing an exception.
routing	Routing is used to route the update request to the right shard and sets the routing for the upsert request if the document being updated doesn’t exist. Can’t be used to update the routing of an existing document.
parent	Parent is used to route the update request to the right shard and sets the parent for the upsert request if the document being updated doesn’t exist. Can’t be used to update the parent of an existing document.
timeout	Timeout waiting for a shard to become available.
consistency	The write consistency of the index/delete operation.
refresh	Refresh the relevant primary and replica shards (not the whole index) immediately after the operation occurs, so that the updated document appears in search results immediately.
fields	Return the relevant fields from the updated document. Specify _source to return the full updated source.
version & version_type	The update API uses the Elasticsearch’s versioning support internally to make sure the document doesn’t change during the update. You can use the version parameter to specify that the document should only be updated if its version matches the one specified. By setting version type to force you can force the new version of the document after update.

The update API does not support external versioning

External versioning (version types external & external_gte) is not supported by the update API as it would result in Elasticsearch version numbers being out of sync with the external system. Use the index API instead.

Explore Elasticsearch Sample Resumes! Download & Edit, Get Noticed by Top Employers!