Skip to content

Versioning

Edit page

Xapiand is concurrent. When documents are created or updated, several requests can change the same document at once, and a client may write from a copy of the document that is already out of date. Xapiand needs a way of telling the client that the document changed under it.

Every document has a _version number that is incremented whenever the document is written. A write that carries no version always applies, and the last write wins. A write that names the version it expects (the version query param, or a _version in the document body) applies only if that is the document’s current version; otherwise it answers 409 Conflict and changes nothing.

For example, the following indexing command will create a document and assign a version to it:

PUT /twitter/user/Kronuz
{
"name": "Germán Méndez Bravo"
}

This is all business as usual. The write answers 204 No Content; with the echo query param it answers the document, and the interesting bit is its _version:

{
"name": "Germán Méndez Bravo",
"_id": "Kronuz",
"_version": 1
}

Notice the _version returned when performing an index operation. This is now the version associated with this particular document. If we get or search for documents in an index, we will get the version as well.

Now, the interesting bits can start, as we can use the versioning feature to perform optimistic concurrency control. We can take advantage of the _version number to ensure that conflicting changes made by our application do not result in data loss. We do this by specifying the version number of the document that we wish to change. If that version is no longer current, our request fails.

Let’s create a new blog post:

PUT /blog/1
{
"title": "My first blog entry",
"text": "Just trying this out..."
}

The response body tells us that this newly created document has _version number 1. Now imagine that we want to edit the document: we load its data into a web form, make our changes, and then save the new version.

First we retrieve the document:

GET /blog/1

The response body includes the same _version number of 1:

{
"title": "My first blog entry",
"text": "Just trying this out...",
"_id": 1,
"_version": 1
}

Now, when we try to save our changes by reindexing the document, we specify the version to which our changes should be applied. We want this update to succeed only if the current _version of this document in our index is version 1, so we pass version=1 as a query param (or _version as part of the document body):

PUT /blog/1?version=1
{
"title": "My first blog entry",
"text": "Starting to get the hang of this..."
}

This request succeeds, and the response body tells us that the _version has been incremented to 2:

{
"title": "My first blog entry",
"text": "Starting to get the hang of this...",
"_id": 1,
"_version": 2
}

However, if we were to rerun the same index request, still specifying version 1, Xapiand would respond with a 409 Conflict HTTP response code. The 409 body carries the document’s current version as _version (0 when there is no document), so a client knows which version to read back.

The version is checked by every write of a document by its ID: PUT, UPDATE, PATCH, UPSERT and DELETE (see Delete). The check runs in the index’s write turn, where the write applies, so two writers that read the same version never both succeed.

A version of 0 stands for a document that does not exist. PUT and UPSERT with version=0 create the document only when no document has that ID, and answer 409 when one does; PATCH, UPDATE and DELETE with version=0 on a missing document answer 404, as they do without a version. Any other version names a document that must be there, so it answers 409 when the document is missing.

PUT /versions/doc/1?version=0
{
"title": "first"
}
PUT /versions/doc/1?version=0
{
"title": "second"
}
PUT /versions/doc/1?version=1
{
"title": "second"
}
GET /versions/doc/1
PUT /versions/doc/1?version=1
{
"title": "third"
}
PATCH /versions/doc/2?version=0
[
{ "op": "add", "path": "/title", "value": "missing" }
]
PUT /versions/doc/2?version=3
{
"title": "missing"
}

Sources: docs/mechanisms/document-ids-and-versions.md; src/database/handler.cc (update, patch: the early check and the 404); src/engine/strata/shard.cc (check_version: a missing document has version 0); src/server/search_views.cc (on_error adds _version to the 409 body; the version query param); _version in the body is read by src/database/schema.cc.