Update Document API
Edit pageThe 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.
Merging
Section titled “Merging”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}Patching and upserting
Section titled “Patching and upserting”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/1UPDATE of a missing document answers 404, and UPSERT creates it:
UPDATE /updateapi/doc/2
{ "user": "Jane"}UPSERT /updateapi/doc/2
{ "user": "Jane"}Scripting
Section titled “Scripting”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.
Commit
Section titled “Commit”By passing the commit query param to the request, you can ensure the operation
returns once the document changes have been committed to disk.
Optimistic Concurrency Control
Section titled “Optimistic Concurrency Control”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.