A newer version of this documentation is available.

View Latest



      Setting an expiry value on a document in a local database

      Related Topics:    access()   |   channel()   |   expiry()   |   requireAccess()   |   requireAdmin()   |   requireRole()   |   requireUser()   |   role()   |   throw()




      Use expiry(value) to set the expiry value (TTL) on the document.


      Argument Description


      The value can be specified in two ways:

      • As an ISO-8601 format: date string — or example the 6th of July 2016 at 17:00 in the BST timezone would be 2016-07-06T17:00:00+01:00;

      • As a numeric Couchbase Server expiry value 1

      1 Couchbase Server expiries are specified as Unix time, and if the desired TTL is below 30 days then it can also represent an interval in seconds from the current time (for example, a value of 5 will remove the document 5 seconds after it is written to Couchbase Server).


      Under the hood, the expiration time is set and managed on the Couchbase Server document (TTL is not supported for databases in walrus mode).


      The impact on the resulting document when the expiry value is reached depends on the setting of shared-bucket-access:


      The active revision of the document is tombstoned.

      If there is another non-tombstoned revision for this document (i.e a conflict) it will become the active revision.

      The tombstoned revision will be purged when the server’s metadata purge interval is reached.


      The document will be purged from the database.

      As with the existing explicit purge mechanism, this applies only to the local database; it has nothing to do with replication.

      This expiration time is not propagated when the document is replicated.

      The purge of the document does not cause it to be deleted on any other database.

      Inspect a Document Expiry Value

      You can retrieve a document’s expiration time, as it is returned in the response of GET +/\{db/{doc} use show_exp=true as the querystring.

      curl -X GET "http://localhost:4985/ourdb/ourdoc?show_exp=true" -H "accept: application/json"


      Example 1. expiry(value)
      expiry("2022-06-23T05:00:00+01:00") (1)
      1 Sets the expiry date to 5am on the 23rd June 2022.