expiry()

    +

    Setting an expiry value on a document in a local database

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

    Function

    expiry(value)

    Purpose

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

    Arguments

    Argument Description

    value

    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).

    Context

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

    Impact

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

    Enabled

    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.

    Disabled

    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"

    Use

    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.