Cloudant Fundamentals : The _rev token

The basics of CouchDB-style revision system that make the database unique (part 3 of 10)

Glynn Bird
May 22, 2018 · 3 min read

In part one of this series we looked at Cloudant JSON, and in part two we saw how an _id is made. In this part we'll focus on the humble _rev token.

When you first create a document, you don’t need to worry about the _rev token — it is generated for you and returned to you in the receipt.

If we create a new document with a body of {"a":1,"b":2}, we get a reply from the database of:

We can see the _id and the _rev if we fetch the document:

Fields starting with the underscore character _ are reserved for Cloudant-specific purposes. You can't add your own custom _name field, for example.

Image for post
Image for post
Lots of trees and branches here, just like you could have when dealing with CouchDB _rev tokens. Photo by Sergei Akulich on Unsplash

What is the _rev token?

The _rev token consists of two parts separated by a hyphen character -:

  • a number that increments with each version of the document
  • a 32-character string that is a cryptographic hash of the document’s body.

Why does Cloudant have a _rev token?

The _rev token keeps track of the revisions that a document goes through in its life:

  1. First revision 1–25f9b97d75a648d1fcd23f0a73d2776e
  2. Second revision 2–524e981baaeec9bbecf92c4c01242308
  3. Third revision 3-e95ca5ca4dc5407fd09b8e0e0acf25fd

Cloudant actually stores revisions in a tree data structure, the simplest form being an ever-growing list of revisions:

Image for post
Image for post
A simple revision tree.

Things can get much more complicated than this when we talk about conflicts but that is for another time.

As to why data is stored like this, it’s because Cloudant was built to work as a distributed database with the data stored across many nodes in a cluster. Distributed systems are complicated, and the revision tree allows the database to handle conflicting writes without losing data, rather like Git would not lose data in a conflicting merge. The revision tree is also essential when replicating data from one location to another. Two databases in any state could be replicated in either direction without loss of data, thanks to the revision tree.

Can I use the revision tree as a version control system for my documents?


Cloudant doesn’t keep the bodies of old revisions (they are destroyed in a process called “compaction”), but the history of revision tokens is retained.

Deleting a document creates another revision

A Cloudant document can never really be deleted. When you do a delete API call another revision is added to the end of the tree:

  1. First revision 1–25f9b97d75a648d1fcd23f0a73d2776e
  2. Second revision 2–524e981baaeec9bbecf92c4c01242308
  3. Third revision 3-e95ca5ca4dc5407fd09b8e0e0acf25fd
  4. Fourth revision 4-d0b8f4e0375c952eb957de7dc1947aef

The last revision will look like this:

Deleting a document leaves this final revision and the tree of revision tokens behind.

I don’t care about revision tokens — make them go away

You can’t really make revision tokens go away, but there are libraries aimed at new starters that hide them from you so you can get on with building your app. Take a look at cloudant-quickstart which does just that.

Even if you are putting your fingers in your ears and pretending that revision tokens don’t exist, they are still being recorded in the database so you should try to avoid modifying the same document over and over if possible and be aware that a deleted document leaves a piece of data behind.

Next time

In the next part we’ll take a look at using Cloudant’s HTTP API using the curl command-line tool.

Center for Open Source Data and AI Technologies

Things we made with data at IBM’s Center for Open Source…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store