Partial Update in Elasticsearch Guide (with Examples)

When working with Elasticsearch, sometimes you want to partially update a document, or update only specific fields in a document instead of the whole document.

For example, you may want to update the phone_number field of a user but not the username field. Or you might want to increase the view_count field of a blog post by 1.

In this tutorial, I will show you how to perform partial updates in Elasticsearch version 8.x to update only specific fields in a document using the Update API.

Contents

• How to Use the Elasticsearch Update API
• Partial Update in Elasticsearch using doc Field
• Partial Update in Elasticsearch using script Field
• Partial Update and Create a New Document if Not Exist in Elasticsearch
• Partial Update and Create a New Document if Not Exist in Elasticsearch using upsert Field
• Conclusion

How to Use the Elasticsearch Update API

The update API allows you to update a document in Elasticsearch.

The syntax of the update API is as follows:

POST <index>/_update/<id>
{
  "script": {
    "source": """
      // some script here
    """,
    "lang": "painless",
    "params": {
      // some params here
    }
  },
  "doc": {
    // fields to update here
  },
  "doc_as_upsert": true, // if the document doesn't exist, the "doc" field will be used to create a new document
  "upsert": {
    // or if the document doesn't exist, fields inside "upsert" will be used to create a new document
    // fields to insert here
  }
}

The required fields are:

• index: the name of the index to update the document in.
• id: the ID of the document to update.

The optional fields are:

• script: a script to run before updating the document. The script can be written in Painless or any other scripting language supported by Elasticsearch.
• doc: the fields to update in the document.
• doc_as_upsert: if the document doesn't exist, the doc field will be used to create a new document.
• upsert: if the document doesn't exist, fields inside upsert will be used to create a new document.

Now, let's see some examples.

Partial Update in Elasticsearch using doc Field

Suppose I have a user document in the users index:

{
  "id": 1,
  "username": "Minh Vu",
  "phone_number": "0123456789"
}

To change the phone_number field to another value, I will use the following request:

POST users/_update/1
{
  "doc": {
    "phone_number": "0987654321"
  }
}

After running the request, the phone_number field will be updated to 0987654321.

I will use the GET /users/_doc/1 request to verify the result:

{
  // other fields
  "_source": {
    "id": 1,
    "username": "Minh Vu",
    "phone_number": "0987654321"
  }
}

Partial Update in Elasticsearch using script Field

Elasticsearch also allows you to update a document using a script.

Suppose I have a blog post document in the posts index:

{
  "id": 1,
  "title": "Partial Update in Elasticsearch Guide (with Examples)",
  "view_count": 100
}

So every time a user views the blog post, I want to increase the view_count field by 1.

To do so, I will use the following request:

POST posts/_update/1
{
  "script": {
    "source": "ctx._source.view_count += params.increase",
    "lang": "painless",
    "params": {
      "increase": 1
    }
  }
}

Here, I put an increase parameter and then add it to the view_count field of the document.

By using the GET /posts/_doc/1 request, I can verify that the view_count field has been increased by 1:

{
  // other fields
  "_source": {
    "id": 1,
    "title": "Partial Update in Elasticsearch Guide (with Examples)",
    "view_count": 101
  }
}

Partial Update and Create a New Document if Not Exist in Elasticsearch

If the document doesn't exist, you can use the doc_as_upsert field to create a new document.

For example, suppose I want to update the age field of a user but if the user doesn't exist, I want to create a new user with the age field.

I will use the user with ID 2 (which doesn't exist) as an example:

POST users/_update/2
{
  "doc": {
    "age": 21
  },
  "doc_as_upsert": true
}

After running the request, the age field will be updated to 21.

I will use the GET /users/_doc/2 request to verify the result:

{
  // other fields
  "_source": {
    "id": 2,
    "age": 21
  }
}

Partial Update and Create a New Document if Not Exist in Elasticsearch using upsert Field

Alternatively, you can use the upsert field to create a new document if the document doesn't exist.

Similar to the previous example, I want to increase the age field of a user by 1. If the user doesn't exist, I want to create a new user with the age field set to 0 initially.

I will use the user with ID 3 (which doesn't exist) as an example:

POST users/_update/3
{
  "script": {
    "source": "ctx._source.age += params.increase",
    "lang": "painless",
    "params": {
      "increase": 1
    }
  },
  "upsert": {
    "age": 0
  }
}

I will get a new user 3 with the age field set to 1.

The result would be:

{
  // other fields
  "_source": {
    "id": 3,
    "age": 1
  }
}

Conclusion

In this tutorial, I have shown you how to perform partial updates in Elasticsearch 8.x to update only specific fields in a document using the Update API.

Thanks for reading and see you next time!