Skip to content

Data Manipulation

Edit page

Xapiand reads its own writes: a document you index, update or delete is visible to the next search or get as soon as the node has answered the write. The index commits to disk 1 s after its last write (3 s while writes keep coming, and 8 to 10 s after the first of them at the latest), or before the answer when the request carries ?commit. A write the node answered with a 2xx is in the write-ahead log and survives a crash either way.

Every PUT, POST, UPDATE, PATCH, UPSERT and DELETE below addresses a document in an index by its path: in /twitter/user/John the index is twitter/user and the document ID is John. The responses shown are those of a node that echoes writes (--echo, -vvvv, or ?echo on the request); see What a write answers for the answers without it.

We’ve previously seen how we can index a single document. Let’s recall that command again:

PUT /twitter/user/John
{
"name": "John Doe"
}

The above will index the specified document into the twitter/user index, with the ID of John. If we then executed the above command again with a different (or same) document, Xapiand will replace (i.e. reindex) a new document on top of the existing one with the ID of John:

PUT /twitter/user/John
{
"name": "John"
}

The above completely overwrites the existent document with the ID of John with the new one.

If, on the other hand, we use a different ID, a new document will be indexed and the existing document(s) already in the index remains untouched.

PUT /twitter/user/Jane
{
"name": "Jane Doe",
"age": 20
}

The above indexes a new document with an ID of Jane.

When indexing, the ID part is optional. If not specified, Xapiand will generate an ID and then use it to index the document. The actual ID Xapiand generates (or whatever we specified explicitly in the previous examples) is returned as part of the index API call.

This example shows how to index a document without an explicit ID:

POST /twitter/user/
{
"name": "Richard Roe"
}

Note that in the above case, we are using the POST verb instead of PUT as we’re not specifying an explicit ID.

In addition to being able to index and replace documents, we can also update existing documents.

This example shows how to update our previous document (ID of John) by adding a gender field to it and leaving the name intact:

UPDATE /twitter/user/John
{
"gender": "male"
}

And the following example shows how to update the same document by adding an age field to it and at the same time changing the name from simply “John” to “Johnny Doe”:

UPDATE /twitter/user/John
{
"name": "Johnny Doe",
"age": 17
}

PATCH applies a JSON Patch (an array of operations) to a document. A body that is not an array of objects answers 400. This example creates a document and then replaces one field, adds another and removes a third:

PUT /twitter/user/Mary
{
"name": "Mary Major",
"age": 31
}
PATCH /twitter/user/Mary
[
{"op": "replace", "path": "/name", "value": "Mary Minor"},
{"op": "add", "path": "/city", "value": "Oslo"},
{"op": "remove", "path": "/age"}
]

UPDATE of a document that does not exist answers 404 Not Found. UPSERT merges like UPDATE when the document exists and creates it when it does not:

UPSERT /twitter/user/Nora
{
"name": "Nora North"
}
UPSERT /twitter/user/Nora
{
"age": 40
}

Updates can also be performed by using simple scripts. This example uses a script to increment the age by 5 and at the same time change the name:

UPDATE /twitter/user/John
{
"name": "John Doe",
"_script": "_doc.age = _old_doc.age + 5"
}

In the above example, _doc is the current document and _old_doc refers to the previous document that is about to be updated.

Deleting a document is fairly straightforward. This example shows how to delete our previous user with the ID of Jane:

DELETE /twitter/user/Jane

Deleting answers 204 No Content, and 404 Not Found when the document does not exist. There is no request that deletes an index; DELETE /twitter/user/ answers 501 Not Implemented:

DELETE /twitter/user/

HEAD answers 200 OK for a document that exists and 404 Not Found for one that does not:

HEAD /twitter/user/John

The index commits on its own, as described at the top of this page. COMMIT commits an index now and answers 200 OK once it is done; the ?commit parameter does the same as part of a write:

COMMIT /twitter/user/

CHECK verifies an index and reports, for each of its shards, the number of errors it found (0 for a sound shard):

CHECK /twitter/user/