New in Couchbase Mobile v1.3: Document Expiration

Document expiration, sometimes referred to as “time to live” , or TTL, has been a feature of Couchbase Server for some time.  The new release of version 1.3 adds this capability to Couchbase Mobile.  Let’s explore a little.

Documents and Revisions

Couchbase stores data in the form of JSON documents.  More precisely, Couchbase stores revisions of documents.  The details go outside the scope of what I want to focus on here, but revisions are important to understand.  You can read more about them in this guide.

Deleting versus Purging

In your local database, you really only want to store what’s necessary.  Let’s suppose for some reason a particular document is no longer relevant.  Say, for example, a transaction has completed, and the user no longer wants to keep the details around.

You could delete the document.  This has two effects.  First, the document isn’t entirely gone locally.  Couchbase Lite keeps some revision information and replaces the document with a “tombstone” entry.  Second, the fact that the document has been deleted gets propagated to any replications.

So deleting a document doesn’t entirely free up space on your device.  And you may not want to delete the document in other copies of the database.  In our example, you can imagine the user doesn’t want the details of the transaction on their device currently, but may want to retrieve them again later.

Purging a document does something quite different.  Purging a document removes all traces of it, but only in the local database.  If you’re syncing your database, it can help to think of a purged document as one that never got replicated locally to begin with.  The document still exists remotely.  In fact, if the remote version changes, the document could show up in the replication feed, so you can end up with a local copy again.

This fits nicely with our example.  A user  no longer cares about the details of a transaction, so the records get removed locally, freeing up space.  If something changes in the details of the transaction, an app could see those changes passed in a replication, and alert the user.

Expiration = Automated Purging

Now, back to document expiration.  I told you that other information to put expiration in context.  When a document expires, it automatically gets treated like it was purged.

To have a document expire, you set an expiration date on it.  Here’s a code snippet that shows how to do that in Java.

You can see that you’re setting an absolute time, not a relative one.  Once that time has passed, the document behaves as if it has been purged.

I say behaves as if it has been purged.  It can take a little time to process things behind the scenes.  The document will actually be purged, but that can get delayed briefly for various reasons.  Just don’t expect millisecond accuracy.

Postscript