Update a document

POST /{index}/_update/{id}

Update a document by running a script or passing a partial document.

If the Elasticsearch security features are enabled, you must have the index or write index privilege for the target index or index alias.

The script can update, delete, or skip modifying the document. The API also supports passing a partial document, which is merged into the existing document. To fully replace an existing document, use the index API. This operation:

Gets the document (collocated with the shard) from the index.
Runs the specified script.
Indexes the result.

The document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation.

The _source field must be enabled to use this API. In addition to _source, you can access the following variables through the ctx map: _index, _type, _id, _version, _routing, and _now (the current timestamp). For usage examples such as partial updates, upserts, and scripted updates, see the External documentation.

Required authorization

Index privileges: write

Path Parameters

Query Parameters

if_primary_term number: Only perform the operation if the document has this primary term.
if_seq_no number SequenceNumber: Only perform the operation if the document has this sequence number.
include_source_on_error boolean · default: true: True or false if to include the document source in the error message in case of parsing errors.
lang string · default: painless: The script language.
refresh enum Refresh · default: false: If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search. If 'wait_for', it waits for a refresh to make this operation visible to search. If 'false', it does nothing with refreshes.; Values: true false wait_for
require_alias boolean · default: false: If true, the destination must be an index alias.
retry_on_conflict number · default: 0: The number of times the operation should be retried when a conflict occurs.
routing union Routing: A custom value used to route operations to a specific shard. Not allowed when index.slice.enabled is true for the target index; use _slice instead.; One of: string or string[]
timeout string Duration · default: 1m: The period to wait for the following operations: dynamic mapping updates and waiting for active shards. Elasticsearch waits for at least the timeout period before failing. The actual wait time could be longer, particularly when multiple waits occur.
wait_for_active_shards WaitForActiveShards · default: 1: The number of copies of each shard that must be active before proceeding with the operation. Set to 'all' or any positive integer up to the total number of shards in the index (number_of_replicas+1). The default value of 1 means it waits for each primary shard to be active.; Values: all index-setting
_source SourceConfigParam · default: true: If false, source retrieval is turned off. You can also specify a comma-separated list of the fields you want to retrieve.
_source_excludes union Fields: The source fields you want to exclude.; One of: Field or Field[]
_source_includes union Fields: The source fields you want to retrieve.; One of: Field or Field[]

Request

Response

application/json

Examples

Run POST test/_update/1 to increment a counter by using a script.

Request Console 1 / 8 languages

Console Kibana Dev Tools

POST test/_update/1
{
  "script" : {
    "source": "ctx._source.counter += params.count",
    "lang": "painless",
    "params" : {
      "count" : 4
    }
  }
}

JavaScript Elasticsearch JavaScript Client

const response = await client.update({
  index: "test",
  id: 1,
  script: {
    source: "ctx._source.counter += params.count",
    lang: "painless",
    params: {
      count: 4,
    },
  },
});

Python Elasticsearch Python Client

resp = client.update(
    index="test",
    id="1",
    script={
        "source": "ctx._source.counter += params.count",
        "lang": "painless",
        "params": {
            "count": 4
        }
    },
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/test/_update/1" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "script": {
      "source": "ctx._source.counter \u002B= params.count",
      "lang": "painless",
      "params": {
        "count": 4
      }
    }
  }'

Java Elasticsearch Java Client

client.update(u -> u
    .id("1")
    .index("test")
    .script(s -> s
        .source(so -> so
            .scriptString("ctx._source.counter += params.count")
        )
        .params("count", JsonData.fromJson("4"))
        .lang("painless")
    )
,Void.class);

C# Elasticsearch .NET Client

var response = await client
    .UpdateAsync<MyDocument, MyDocument>(index: "test", id: "1", d1 => d1
        .Script(d2 => d2
            .Lang(ScriptLanguage.Painless)
            .Params(new Dictionary<string, object>()
            {
                { "count", 4 }
            })
            .Source("ctx._source.counter += params.count")
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->update([
    "index" => "test",
    "id" => "1",
    "body" => [
        "script" => [
            "source" => "ctx._source.counter += params.count",
            "lang" => "painless",
            "params" => [
                "count" => 4,
            ],
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.update(
  index: "test",
  id: "1",
  body: {
    "script": {
      "source": "ctx._source.counter += params.count",
      "lang": "painless",
      "params": {
        "count": 4
      }
    }
  }
)

Response

{
   "_shards": {
        "total": 0,
        "successful": 0,
        "failed": 0
   },
   "_index": "test",
   "_id": "1",
   "_version": 2,
   "_primary_term": 1,
   "_seq_no": 1,
   "result": "noop"
}

Run POST test/_update/1 to perform a scripted upsert. When scripted_upsert is true, the script runs whether or not the document exists.

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST test/_update/1
{
  "scripted_upsert": true,
  "script": {
    "source": """
      if ( ctx.op == 'create' ) {
        ctx._source.counter = params.count
      } else {
        ctx._source.counter += params.count
      }
    """,
    "params": {
      "count": 4
    }
  },
  "upsert": {}
}

curl Shell

curl -X POST "$ELASTICSEARCH_URL/test/_update/1" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "scripted_upsert": true,
  "script": {
    "source": """
      if ( ctx.op == '\''create'\'' ) {
        ctx._source.counter = params.count
      } else {
        ctx._source.counter += params.count
      }
    """,
    "params": {
      "count": 4
    }
  },
  "upsert": {}
}'

Response

{
   "_shards": {
        "total": 0,
        "successful": 0,
        "failed": 0
   },
   "_index": "test",
   "_id": "1",
   "_version": 2,
   "_primary_term": 1,
   "_seq_no": 1,
   "result": "noop"
}

Run POST test/_update/1 to perform a doc as upsert. Instead of sending a partial doc plus an upsert doc, you can set doc_as_upsert to true to use the contents of doc as the upsert value.

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST test/_update/1
{
  "doc": {
    "name": "new_name"
  },
  "doc_as_upsert": true
}

curl Shell

curl -X POST "$ELASTICSEARCH_URL/test/_update/1" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "doc": {
    "name": "new_name"
  },
  "doc_as_upsert": true
}'

Response

{
   "_shards": {
        "total": 0,
        "successful": 0,
        "failed": 0
   },
   "_index": "test",
   "_id": "1",
   "_version": 2,
   "_primary_term": 1,
   "_seq_no": 1,
   "result": "noop"
}

Run POST test/_update/1 to use a script to add a tag to a list of tags. In this example, it is just a list, so the tag is added even it exists.

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST test/_update/1
{
  "script": {
    "source": "ctx._source.tags.add(params.tag)",
    "lang": "painless",
    "params": {
      "tag": "blue"
    }
  }
}

curl Shell

curl -X POST "$ELASTICSEARCH_URL/test/_update/1" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "script": {
    "source": "ctx._source.tags.add(params.tag)",
    "lang": "painless",
    "params": {
      "tag": "blue"
    }
  }
}'

Response

{
   "_shards": {
        "total": 0,
        "successful": 0,
        "failed": 0
   },
   "_index": "test",
   "_id": "1",
   "_version": 2,
   "_primary_term": 1,
   "_seq_no": 1,
   "result": "noop"
}

Run POST test/_update/1 to use a script to remove a tag from a list of tags. The Painless function to remove a tag takes the array index of the element you want to remove. To avoid a possible runtime error, you first need to make sure the tag exists. If the list contains duplicates of the tag, this script just removes one occurrence.

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST test/_update/1
{
  "script": {
    "source": "if (ctx._source.tags.contains(params.tag)) { ctx._source.tags.remove(ctx._source.tags.indexOf(params.tag)) }",
    "lang": "painless",
    "params": {
      "tag": "blue"
    }
  }
}

curl Shell

curl -X POST "$ELASTICSEARCH_URL/test/_update/1" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "script": {
    "source": "if (ctx._source.tags.contains(params.tag)) { ctx._source.tags.remove(ctx._source.tags.indexOf(params.tag)) }",
    "lang": "painless",
    "params": {
      "tag": "blue"
    }
  }
}'

Response

{
   "_shards": {
        "total": 0,
        "successful": 0,
        "failed": 0
   },
   "_index": "test",
   "_id": "1",
   "_version": 2,
   "_primary_term": 1,
   "_seq_no": 1,
   "result": "noop"
}

Run POST test/_update/1 to use a script to add a field new_field to the document.

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST test/_update/1
{
  "script" : "ctx._source.new_field = 'value_of_new_field'"
}

curl Shell

curl -X POST "$ELASTICSEARCH_URL/test/_update/1" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "script" : "ctx._source.new_field = '\''value_of_new_field'\''"
}'

Response

{
   "_shards": {
        "total": 0,
        "successful": 0,
        "failed": 0
   },
   "_index": "test",
   "_id": "1",
   "_version": 2,
   "_primary_term": 1,
   "_seq_no": 1,
   "result": "noop"
}

Run POST test/_update/1 to use a script to remove a field new_field from the document.

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST test/_update/1
{
  "script" : "ctx._source.remove('new_field')"
}

curl Shell

curl -X POST "$ELASTICSEARCH_URL/test/_update/1" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "script" : "ctx._source.remove('\''new_field'\'')"
}'

Response

{
   "_shards": {
        "total": 0,
        "successful": 0,
        "failed": 0
   },
   "_index": "test",
   "_id": "1",
   "_version": 2,
   "_primary_term": 1,
   "_seq_no": 1,
   "result": "noop"
}

Run POST test/_update/1 to use a script to remove a subfield from an object field.

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST test/_update/1
{
  "script": "ctx._source['my-object'].remove('my-subfield')"
}

curl Shell

curl -X POST "$ELASTICSEARCH_URL/test/_update/1" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "script": "ctx._source['\''my-object'\''].remove('\''my-subfield'\'')"
}'

Response

{
   "_shards": {
        "total": 0,
        "successful": 0,
        "failed": 0
   },
   "_index": "test",
   "_id": "1",
   "_version": 2,
   "_primary_term": 1,
   "_seq_no": 1,
   "result": "noop"
}

Run POST test/_update/1 to change the operation that runs from within the script. For example, this request deletes the document if the tags field contains green, otherwise it does nothing (noop).

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST test/_update/1
{
  "script": {
    "source": "if (ctx._source.tags.contains(params.tag)) { ctx.op = 'delete' } else { ctx.op = 'noop' }",
    "lang": "painless",
    "params": {
      "tag": "green"
    }
  }
}

curl Shell

curl -X POST "$ELASTICSEARCH_URL/test/_update/1" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "script": {
    "source": "if (ctx._source.tags.contains(params.tag)) { ctx.op = '\''delete'\'' } else { ctx.op = '\''noop'\'' }",
    "lang": "painless",
    "params": {
      "tag": "green"
    }
  }
}'

Response

{
   "_shards": {
        "total": 0,
        "successful": 0,
        "failed": 0
   },
   "_index": "test",
   "_id": "1",
   "_version": 2,
   "_primary_term": 1,
   "_seq_no": 1,
   "result": "noop"
}

Run POST test/_update/1 to do a partial update that adds a new field to the existing document.

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST test/_update/1
{
  "doc": {
    "name": "new_name"
  }
}

curl Shell

curl -X POST "$ELASTICSEARCH_URL/test/_update/1" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "doc": {
    "name": "new_name"
  }
}'

Response

{
   "_shards": {
        "total": 0,
        "successful": 0,
        "failed": 0
   },
   "_index": "test",
   "_id": "1",
   "_version": 2,
   "_primary_term": 1,
   "_seq_no": 1,
   "result": "noop"
}

Run POST test/_update/1 to perfom an upsert. If the document does not already exist, the contents of the upsert element are inserted as a new document. If the document exists, the script is run.

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST test/_update/1
{
  "script": {
    "source": "ctx._source.counter += params.count",
    "lang": "painless",
    "params": {
      "count": 4
    }
  },
  "upsert": {
    "counter": 1
  }
}

curl Shell

curl -X POST "$ELASTICSEARCH_URL/test/_update/1" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "script": {
    "source": "ctx._source.counter += params.count",
    "lang": "painless",
    "params": {
      "count": 4
    }
  },
  "upsert": {
    "counter": 1
  }
}'

Response

{
   "_shards": {
        "total": 0,
        "successful": 0,
        "failed": 0
   },
   "_index": "test",
   "_id": "1",
   "_version": 2,
   "_primary_term": 1,
   "_seq_no": 1,
   "result": "noop"
}

Required authorization

Path Parameters { index , id , }

Query Parameters { if_primary_term , if_seq_no , include_source_on_error , lang , refresh , require_alias , retry_on_conflict , routing , timeout , wait_for_active_shards , _source , _source_excludes , _source_includes , }

Request { detect_noop , doc , doc_as_upsert , script , scripted_upsert , _source , upsert , }

Response

Path Parameters

Query Parameters

Request