A newer version of this documentation is available.

View Latest

Document expiration

Most data in a database is there to be persisted and long lived. However the need for transient or temporary data does arise in applications, such as in the case of user sessions, caches, or temporary documents representing a given process ownership. You can use expiration values on documents to handle transient data.

In databases without a built-in expiration feature, dealing with transient data may be cumbersome. To provide "expiration" semantics, applications are forced to record a time stamp in a record, and then upon each access of the record, check the time stamp, and if invalid, delete it.

Since some logically ‘expired’ documents may never be accessed by the application, in order to ensure that temporary records to not persist and occupy storage, a scheduled process is typically also employed to routinely scan the database for expired entries, purging those entries that are no longer valid.

Workarounds such as those described above are not required for Couchbase, as Couchbase allows applications to declare the lifetime of a given document, eliminating the need to embed "validity" information in documents and eliminating the need for a routine "purge" of logically expired data.

When an application attempts to access a document which has already expired, the server will indicate to the client that the item is not found. The server internally handles the process of determining the validity of the document and removing older, expired documents (See "Performance" section below).

Setting expiration with SDKs

By default, Couchbase documents do not expire, however the expiration value may be set for the upsert, replace, and insert APIs when modifying data.

Additionally, Couchbase offers two unique APIs to deal with expiration without modifying the contents of the document.

The getAndTouch API allows an application to retrieve a document while modifying its expiration time. This method is useful when reading session data from the database: since accessing the data is indicative of it still being "alive", getAndTouch provides a natural way to extend its lifetime.

Some SDKs expose getAndTouch as an option to get

The touch API allows an application to modify a document’s expiration time without otherwise accessing the document. This method is useful when an application is handling a user session but does not need to access the database (for example, if a certain document is already cached locally).

Examples of setting expiry with SDKs:

C | Python | Java | .NET | Go | node.js

Expiry value

For Couchbase SDKs which accept simple integer expiry values (as opposed to a proper date or time object) allow expiration to be specified in two flavors.

  1. As an offset from the current time.

  2. As an absolute Unix time stamp

If the absolute value of the expiry is less than 30 days (i.e. 60 * 60 * 24 * 30), it is considered an offset. If it is greater, it is considered an absolute time stamp. It may be preferable for applications to normalize the expiration value (i.e. by always converting it to an absolute time stamp) in order to avoid issues when the intended offset is larger than 30 days (in which case it is taken to mean a Unix time stamp and will result in the document automatically expiring as soon as it is stored).

If you wish to use the expiry feature, then you should supply the expiry value for every mutation operation
When dealing with expiration, it is important to note that most operations will implicitly remove any existing expiration. Thus when modifying a document with expiration, it is important to pass the desired expiration time.

Performance considerations

Operations on expired documents perform as quickly as their non-expiry counterparts.

Note that expired documents are not deleted from the server as soon as they expire. While a request to the server for an expired document will receive a response indicating the document does not exist, expired documents are actually deleted (i.e. cease to occupy storage and RAM) when an expiry pager is run. The expiry pager is a routine internal process which scans the database for items which have expired and promptly removes them from storage.

When gathering resource usage statistics, note that expired-but-not-purged items (i.e. the expiry pager has not scanned this item yet) will still be considered with respect to the overall storage size and item count.