In this tutorial, we move beyond simple field replacement and explore scripted updates, which allow you to update a document dynamically based on its current values. This concept is very similar to how updates are performed in SQL, where you can increment or modify a column using its existing value rather than explicitly calculating the new value on the client side.

Scripted updates are especially useful when you want Elasticsearch itself to perform calculations, conditional logic, or small transformations directly on the document.

Motivation: Comparing with SQL-Style Updates

In a traditional SQL database, if you want to increase the price of a book by 1 for a given ID, you might write something like:

UPDATE books SET price = price + 1 WHERE id = 15;

This is concise, expressive, and avoids the need to fetch the record first. Until now, in Elasticsearch, we have mostly been directly setting field values, such as replacing price with a new number. That approach works, but it requires you to already know the new value.

Scripted updates bring this SQL-like behavior to Elasticsearch.

The Scripted Update Endpoint

Even when using scripts:

• The endpoint remains the same
  /{index}/_update/{id}
• The HTTP method is still POST
• Instead of doc, we use script

The script tells Elasticsearch what logic to execute against the existing document.

Understanding the Script Context (ctx)

Inside a scripted update, Elasticsearch provides a predefined context object called ctx.

Conceptually, you can think of it like this:

• ctx._source → represents the current document
• ctx._source.price → represents the price field inside that document

Any changes you make to ctx._source are persisted back to the index once the script finishes executing.

Example 1: Incrementing a Field Value

Let us start with document ID 15.

First, retrieve the document to understand its current state:

GET books/_doc/15

Assume the response shows:

{
  "price": 10
}

Now, let us increase the price by 1 using a scripted update:

POST books/_update/15
{
  "script": {
    "source": "ctx._source.price = ctx._source.price + 1"
  }
}

Result

• Elasticsearch executes the script on the server.
• The document is updated.
• The response shows "result": "updated".

Fetching the document again confirms:

{
  "price": 11
}

Example 2: Using Increment Operators

For simple increments, you can also use shorthand operators:

POST books/_update/15
{
  "script": {
    "source": "ctx._source.price++"
  }
}

After executing this request, the price increases again:

{
  "price": 12
}

This style is clean and readable when you only need to increment by one.

Example 3: Parameterized Scripts with params

Hardcoding values inside scripts is not always ideal. Elasticsearch allows you to parameterize scripts, making them safer, cleaner, and reusable.

POST books/_update/15
{
  "script": {
    "source": "ctx._source.price += params.increment",
    "params": {
      "increment": 35
    }
  }
}

How This Works

• params.increment refers to the value passed in the params object.
• Elasticsearch substitutes the value at runtime.
• This avoids embedding constants directly into the script.

If the price was 12, it now becomes:

{
  "price": 47
}

Example 4: Flexible Parameter Naming

Parameter names are completely flexible. For example:

POST books/_update/15
{
  "script": {
    "source": "ctx._source.price += params.amount",
    "params": {
      "amount": 3
    }
  }
}

After execution, the price becomes:

{
  "price": 50
}

This flexibility makes scripts expressive and easy to adapt to different use cases.

Example 5: Conditional (Multi-line) Scripted Updates

Scripted updates are not limited to single-line expressions. You can also write multi-line scripts with conditions, similar to Java-style if-else logic.

Let us inspect book ID 3 first:

GET books/_doc/3

Assume the document contains:

{
  "price": 10,
  "year": 1926
}

Now apply the following logic:

• If year < 1950 → set price to 20
• Else → set price to 15

POST books/_update/3
{
  "script": {
    "source": """
      if (ctx._source.year < 1950) {
        ctx._source.price = 20;
      } else {
        ctx._source.price = 15;
      }
    """
  }
}

Result

Since the year is 1926, which is less than 1950, the price is updated to:

{
  "price": 20
}

This demonstrates how scripted updates can apply business rules directly inside Elasticsearch.

Pros and Cons of Scripted Updates

Advantages

• Scripted updates eliminate the need for a separate read request, because the logic runs directly on the existing document, significantly reducing network round trips.
• They are well-suited for simple arithmetic, counters, and string manipulation, which would otherwise require fetching and recalculating values on the client side.
• They enable conditional logic, allowing you to apply rules and transformations directly within Elasticsearch.

Disadvantages

• There is a performance overhead, because scripts are sent as strings and must be interpreted and executed at runtime by Elasticsearch.
• Scripts consume CPU and memory on the Elasticsearch nodes, since execution happens on the server side rather than the client.
• Complex scripts with many conditions can become hard to debug and maintain, especially when something goes wrong in production.