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.

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!

Partial Update in Elasticsearch Guide (with Examples)

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

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

Most Read