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).

Required authorization

Authentication

Api key

Authorization: <value>

Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:

		curl -X GET "${ES_URL}/_cat/indices?v=true" \
  -H "Authorization: ApiKey ${API_KEY}"

To get API keys, use the /_security/api_key APIs.

Basic

Authorization: Basic <credentials>

Bearer

Authorization: Bearer <token>

Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API. For examples, refer to Token-based authentication services

Path parameters

Query parameters

if_primary_term number: Only perform the operation if the document has this primary term.
if_seq_no number: 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 · 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 string: A custom value used to route operations to a specific shard.
timeout string · 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 union · 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 union · 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 oneOf: The source fields you want to exclude.; One of: string[] or string
_source_includes union oneOf: The source fields you want to retrieve.; One of: string[] or string

Request body

Response

application/json

_id string required: The unique identifier for the added document.
_index string required: The name of the index the document was added to.
_primary_term number: The primary term assigned to the document for the indexing operation.
result enum required: The result of the indexing operation: created or updated.; Values: created updated deleted not_found noop
_seq_no number: The sequence number assigned to the document for the indexing operation. Sequence numbers are used to ensure an older version of a document doesn't overwrite a newer version.
_shards object required: Information about the replication process of the operation.
_version number required: The document version, which is incremented each time the document is updated.
failure_store enum: The role of the failure store in this document response; Values: not_applicable_or_unknown used not_enabled failed
forced_refresh boolean
get object

Examples

Request Console 1 / 8 languages

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

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

By default updates that don't change anything detect that they don't change anything and return "result": "noop".

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

Request Console 1 / 2 languages

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

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": {}
}

Generated from the API spec

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": {}
}'

Generated from the API spec

Response

By default updates that don't change anything detect that they don't change anything and return "result": "noop".

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

Request Console 1 / 2 languages

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.

Console Kibana Dev Tools

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

Generated from the API spec

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
  }'

Generated from the API spec

Response

By default updates that don't change anything detect that they don't change anything and return "result": "noop".

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

Request Console 1 / 2 languages

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.

Console Kibana Dev Tools

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

Generated from the API spec

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"
      }
    }
  }'

Generated from the API spec

Response

By default updates that don't change anything detect that they don't change anything and return "result": "noop".

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

Request Console 1 / 2 languages

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.

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"
    }
  }
}

Generated from the API spec

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"
      }
    }
  }'

Generated from the API spec

Response

By default updates that don't change anything detect that they don't change anything and return "result": "noop".

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

Request Console 1 / 2 languages

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

Console Kibana Dev Tools

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

Generated from the API spec

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'\''"
  }'

Generated from the API spec

Response

By default updates that don't change anything detect that they don't change anything and return "result": "noop".

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

Request Console 1 / 2 languages

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

Console Kibana Dev Tools

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

Generated from the API spec

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'\'')"
  }'

Generated from the API spec

Response

By default updates that don't change anything detect that they don't change anything and return "result": "noop".

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

Request Console 1 / 2 languages

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

Console Kibana Dev Tools

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

Generated from the API spec

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'\'')"
  }'

Generated from the API spec

Response

By default updates that don't change anything detect that they don't change anything and return "result": "noop".

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

Request Console 1 / 2 languages

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).

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"
    }
  }
}

Generated from the API spec

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"
      }
    }
  }'

Generated from the API spec

Response

By default updates that don't change anything detect that they don't change anything and return "result": "noop".

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

Request Console 1 / 2 languages

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

Console Kibana Dev Tools

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

Generated from the API spec

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"
    }
  }'

Generated from the API spec

Response

By default updates that don't change anything detect that they don't change anything and return "result": "noop".

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

Request Console 1 / 2 languages

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.

Console Kibana Dev Tools

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

Generated from the API spec

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
    }
  }'

Generated from the API spec

Response

By default updates that don't change anything detect that they don't change anything and return "result": "noop".

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

Required authorization

Authentication

Path parameters

Query parameters

Request body { }

Response

Request body