Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Expiration

    +
    Time To Live (TTL) imposes a maximum lifespan on items within a bucket or a collection, and thus ensures the expiration of such items, once the specified period is complete.

    Overview

    TTL is a non-negative integer-value, specified per bucket or per collection, that determines the maximum expiration time of individual items within the bucket or collection: if TTL is enabled, each newly created item lives for the number of seconds specified by TTL, following the item’s creation. After its expiration time is reached, the item will be deleted by Couchbase Server. Deleted items and their contents are no longer available: access-attempts are treated as if the items never existed.

    The maximum value for TTL is MAX32INT seconds (2147483648, or 68.096 years). The default value is 0, which indicates that TTL is disabled. If TTL is changed from the default, it is thereby enabled.

    Whenever TTL is modified, items that existed prior to the modification:

    • Remain subject to the previous TTL, if TTL was previously enabled.

    • Remain subject to no TTL, if TTL was not previously enabled.

    Items created or modified following the modification of TTL are subject to the modified TTL.

    TTL can be established on Couchbase and Ephemeral buckets: it cannot be established on Memcached buckets. TTL can be established on collections: it cannot be established on scopes. Note that TTL is only available in the Enterprise Edition of Couchbase Server.

    Expiration: Bucket, Collection, and Item

    As described in Document Expiration, an expiration time can be specified per document, by means of Couchbase SDK APIs: this is referred to as the item’s TTL.

    In cases where an item has a TTL, the item’s TTL may need to be modified, depending on the TTL of either its bucket or its collection:

    • If an item resides within a collection that has no TTL, and the collection resides within a bucket that does have a TTL, the bucket’s TTL is used to determine whether and how the item’s TTL is modified.

    • If an item resides within a collection that has its own TTL, and the collection resides within a bucket that has no TTL, the collection’s TTL is used to determine whether and how the item’s TTL is modified.

    • If an item resides within a collection that has its own TTL, and the collection resides within a bucket that also has its own TTL, the bucket’s TTL is ignored, and only the collection’s TTL is used, to determine whether and how the item’s TTL is modified.

    Determination of whether and how to modify the item’s TTL is as follows. If a new item’s TTL is:

    • Above that of the bucket’s or the collection’s TTL, the item’s TTL is reduced to the value of the bucket’s or the collection’s TTL.

    • Below that of the bucket’s or the collection’s TTL, the item’s TTL is left unchanged.

    • 0, the item’s TTL is reset to the value of the bucket’s or the collection’s TTL.

    TTL Use Cases

    TTL is intended for use with buckets and collections containing data that either must or can be permitted to expire after a certain period of time.

    TTL must not be used with buckets whose data is required not to expire: for example, the buckets that support Couchbase Eventing and Couchbase Mobile. If TTL is used with such buckets, system failures may result.

    Post-Expiration Purging

    When its expiration time is reached, an item is deleted as soon as one of the following occurs:

    • An attempt is made to access the item.

    • The expiry pager is run. For information on the expiry pager, see Memory.

    • Compaction is run. For information on performing compaction with the Couchbase CLI, see bucket-compact; with Couchbase REST APIs, see Compaction API; with the Couchbase Web Console (as auto-compaction), see Auto-Compaction.

    As described in Storage Settings, for each collection or item that is deleted, a tombstone continues to be maintained by Couchbase Server for some period of time, as a record: this applies to all instances of item-deletion, including those achieved by specifying TTL. To ensure that no trace of deleted items remains, tombstones are removed through a Metadata Purge. This is an automatic, non-disruptive background-process, which can be scheduled if necessary by means of Couchbase Web Console; as described in Auto-Compaction. Note that the console allows the intervals between purges to be established as appropriately low, so that tombstones are removed promptly.

    Expiration and XDCR

    When Cross Data-Center Replication occurs, the bucket or collection TTL setting does not get propagated from the source to the target. However, items within the source that have individual expiration times, including ones derived from the source bucket or collection TTL setting, are replicated to the target along with their individual expiration times.

    Buckets and collections on the target cluster can have their own TTL settings, which may differ from those of the buckets and collections in the source. If, on the target cluster, the TTL of a replicated item is:

    • Above that of the bucket’s or the collection’s TTL, the item’s TTL is reduced to the value of the bucket’s or the collection’s TTL.

    • Below that of the bucket’s or the collection’s TTL, the item’s TTL is left unchanged.

    • 0, the item’s TTL is reset to the value of the bucket’s or the collection’s TTL.

    Note that in cases where the TTL of the replicated item is above that of the bucket’s or the collection’s TTL or is 0, if bi-directional XDCR has been set up, the TTL of the item at the source is eventually also either reduced or reset to the value of the target’s bucket or collection TTL.

    Note also that when an item is replicated by XDCR, its expiration time is communicated to the target as absolute. This requires that the system clocks of the respective clusters be fully synchronized; otherwise, inconsistent behavior may result (as, for example, in the case where an item arrives at the target-cluster with an absolute expiration time that is earlier than the current time acknowledged by the target-cluster). See Clock Sync with NTP.

    Note that optionally, TTL can be omitted from a document replicated by means of XDCR. For details, see Deletion Filters.

    Setting Expiration on Buckets and Collections

    An expiration time can be set for a bucket by means of any of the following:

    An expiration time can be set for a collection by means of:

    For information on roles that allow modification of bucket and collection settings, see Roles.

    Auditing

    If auditing is switched on, changes to each bucket’s expiration time are recorded, and can be subsequently viewed. See Auditing.