Skip to content

Update Document API

Edit page

The Update API allows to update a document based on the existent content of a document. The operation gets the current document from the index, merges the new data with the data in the current document, optionally it can also run a script, and indexes back the result. It internally and automatically uses versioning to make sure this operation is atomic.

If the document does not already exist, UPDATE answers 404 Not Found. The UPSERT method does the same as UPDATE and, when the document does not exist, adds the body of the request as a new document, the exact same way as the Index API does it, just with the little extra overhead of trying to retrieve the current document first.

For example, let’s index a simple doc:

PUT /twitter/tweet/1
{
"user": "Kronuz",
"post_date": "2019-03-22T14:35:26",
"message": "Trying out Xapiand",
"likes": 0,
"hashtags": ["#xapiand"]
}

The result of the above index operation is a 204 No Content HTTP response code. As with every write, the echo query param makes the operation answer the stored document, with its _id and _version.

The following update adds a new field to the existing document by merging the passed fields (simple recursive merge, inner merging of objects, replacing core “keys/values”and arrays):

UPDATE /twitter/tweet/1
{
"title": "Xapiand Rocks!"
}

The stored document is now:

{
"user": "Kronuz",
"post_date": "2019-03-22T14:35:26",
"message": "Trying out Xapiand",
"likes": 0,
"hashtags": [
"#xapiand"
],
"title": "Xapiand Rocks!",
"_id": 1,
"_version": 2
}

PATCH applies a JSON Patch (an array of add, remove, replace, move, copy and test operations) to the document instead of merging a body:

PUT /updateapi/doc/1
{
"user": "Kronuz",
"likes": 0
}
PATCH /updateapi/doc/1
[
{ "op": "replace", "path": "/likes", "value": 5 },
{ "op": "add", "path": "/title", "value": "Patched" }
]

Like every write, PATCH answers 204 No Content, and with the echo query param 200 OK with the patched document. Reading it back:

GET /updateapi/doc/1

UPDATE of a missing document answers 404, and UPSERT creates it:

UPDATE /updateapi/doc/2
{
"user": "Jane"
}
UPSERT /updateapi/doc/2
{
"user": "Jane"
}

Now, we can execute a script that would increment the number of likes:

UPDATE /twitter/tweet/1
{
"_script": "_doc.likes = _old_doc.likes + 1"
}

We can add a tag to the list of hashtags (if the tag exists, it still gets added, since this is a list):

UPDATE /twitter/tweet/1
{
"_script": {
"_body": "table.insert(_doc.hashtags, tag)",
"_params": {
"tag": "#trying"
}
}
}

We can remove a tag from the list of hashtags:

UPDATE /twitter/tweet/1
{
"_script": {
"_body": "for i = #_doc.hashtags, 1, -1 do if _doc.hashtags[i] == tag then table.remove(_doc.hashtags, i) end end",
"_params": {
"tag": "#trying"
}
}
}

We can also programmatically add a new field to the document:

UPDATE /twitter/tweet/1
{
"_script": {
"_body": "_doc[field] = value",
"_params": {
"field": "new_field",
"value": "value_of_new_field"
}
}
}

Or remove a field from the document:

UPDATE /twitter/tweet/1
{
"_script": {
"_body": "_doc[field] = nil",
"_params": {
"field": "new_field",
}
}
}

See the Scripting section for more details about scripts and the scripting language.

By passing the commit query param to the request, you can ensure the operation returns once the document changes have been committed to disk.

Update operations can be made conditional and only be performed if the last current document version matches the passed version in the query param. If a mismatch is detected, the operation will result in a 409 Conflict HTTP response code. See Versioning for more details.

Sources: the verbs, src/server/search_views.cc:1000-1060 and the route table :575-579; src/database/handler.cc:603-660 (PATCH) and :1087-1102.