Manage Expiration

Enterprise Edition

You can have documents in your Couchbase Server Enterprise Edition automatically expire after a period of time. See Expiration for an overview of this feature.

Set Expiration at the Document Level

You can set a document to expire either when you create it or when you mutate it. The expiration value is the number of seconds in the future from the time of creation or mutation when you want the document to expire. When this period of time elapses, Couchbase Server deletes the document unless you mutate the document beforehand.

The expiration is part of the document’s metadata. You can set the expiration when creating a document. This example uses SQL++ to create a new document in the user_sessions bucket and sets it to expire in one hour:

INSERT INTO user_sessions (KEY, VALUE, OPTIONS) VALUES (
    "123456",
    {
        "username": "jsmith@example.com",
        "ip_address" : "192.168.10.20",
        "cart" : []
    },
    {
        "expiration": 3600
    }
);

To view the expiration of a document, query its metadata to find its expiration setting. This SQL++ example queries the document created by the prior example using its id.

SELECT meta().expiration
    FROM user_sessions
    USE KEYS '123456';

The result of running the previous looks like this:

[
  {
    "expiration": 1704819228
  }
]

The expiration value is the UNIX-epoch timestamp when the document expires.

You can change the document’s expiration by setting its expiration value during a mutation. The following example updates the document with new values and also resets its expiration so it expires one hour after the statement executes.

UPDATE user_sessions AS U
    USE KEYS "123456"
    SET meta(U).expiration = 3600, cart = [{"item": "9999", "quantity": "3"}]

Querying the document’s metadata shows that the expiration timestamp is now later than before:

[
  {
    "expiration": 1704829288
  }
]

Mutation’s Effect on Expiration

By default, if you mutate a document without setting its expiration, Couchbase Server automatically sets the value to 0. This value prevents the document from expiring unless the collection or bucket has a non-zero maxTTL setting. For example, suppose you execute the following SQL++ statement to update the document from the previous examples:

UPDATE user_sessions
    USE KEYS "123456"
    SET cart = [{"item": "9999", "quantity": "3"}, {"item" : "3423", "quantity" : 1}];

If you then query the document’s expiration metadata, you’ll find that it’s now 0:

[
  {
    "expiration": 0
  }
]

You can prevent Couchbase Server from clearing the expiration value by using the preserve_expiry request-level parameter.

You can directly preserve a document’s expiration when mutating it. To preserve the expiration, set the expiration metadata to the document’s current expiration value. For example, you can alter the previous example statement to preserve the existing expiration value:

UPDATE user_sessions AS u
    USE KEYS "123456"
    SET cart = [{"item": "9999", "quantity": "3"}, {"item" : "3423", "quantity" : 2}],
        meta(u).expiration = meta(u).expiration;

Set Document Expiration Using the SDKs

All SDKs let you set the document’s expiration when creating it. The SDKs have an option named expiry to set the expiration for a document. For example, to set the expiration of when creating a document using the Python SDK, use the insert method’s expiry parameter. The following example creates a document and sets its expiration to 1 hour.

from datetime import timedelta
from couchbase.auth import PasswordAuthenticator
from couchbase.cluster import Cluster
from couchbase.options import (ClusterOptions, InsertOptions)

auth = PasswordAuthenticator(
    "Administrator",
    "password",
)

cluster = Cluster('couchbase://localhost', ClusterOptions(auth))
cluster.wait_until_ready(timedelta(seconds=5))

# Prepare to insert document into the live_site collection, of the store scope in the
# user_sessions bucket.
cb = cluster.bucket("user_sessions")
live_site = cb.scope("store").collection("live_site")

# Create a document ot insert, set options.
document = {"username": "jdoe@example.com",
            "ip_address": "192.168.10.54",
            "cart": [ {"item": "4321", "quantity": "1"}]
           }
opts = InsertOptions(timeout=timedelta(seconds=5))

# Insert document and set expiration to 1 hour.
result = live_site.insert("jdoe_example_com",
                           document,
                           opts,
                           expiry=timedelta(seconds=3600))

# Normally, you'd do something useful with the response. This example
# just prints it.
print(result)

See the SDK documentation for more information about setting and getting the expiration of documents.

Set Buckets and Collections to Automatically Expire Documents

By default, documents expire only if you explicitly set their expiration values. You can have collections and buckets set their documents to automatically expire by changing their maxTTL setting. Setting maxTTL to a non-zero value has two effects:

Couchbase Server sets a default expiration for all documents you create or mutate in the collection or bucket unless you explicitly set the expiration to a smaller value.
You cannot explicitly set a document’s expiration to be longer than the maxTTL setting. If you try to set the expiration to a value larger than the collection or bucket’s maxTTL setting, Couchbase Server uses the maxTTL value instead.

You can set the maxTTL setting for buckets and collections when you initially create them. You can change the maxTTL setting of a bucket after you create it.

Set maxTTL Using Couchbase Server Web Console

When you create a new bucket or collection using the Web Console, you can enable the maxTTL setting.

To enable automatically expiring documents when creating a bucket using the Web Console:

In the Add Data Bucket dialog, expand the Advanced bucket settings section.
Under Bucket Max Time-To-Live select Enable.
In the text field, enter the default TTL for documents in seconds.

To enable expiration when creating a collection using the Web Console, enter a non-zero value in the Add Collection to scope name Scope dialog’s Collection Max Time-To-Live field.

You can also use the Web Console to change the maxTTL setting of an existing bucket:

Click Buckets.
Click the name of the bucket whose maxTTL setting you want to change.
Click Edit.
Expand the Advanced bucket settings section.
Under Bucket Max Time-To-Live, select or clear the Enable box to enable or turn off automatic expiration. , If you’re enabling automatic expiration, enter the number of seconds the documents should exist before expiring in the text field.
Click Save Changes.

You cannot change the maxTTL of a collection after you create it.

Set maxTTL Using the REST API

The REST API has endpoints for creating and editing collections and buckets. These endpoints let you set a collection or bucket’s the maxTTL setting on creation.

The following example gets the value of maxTTL of a bucket named user_sessions, then sets it using the /pools/default/buckets endpoint:

curl -s -X GET -u Administrator:password \
      http://localhost:8091/pools/default/buckets/user_sessions  \
      | jq '{maxTTL: .maxTTL}'
{
  "maxTTL": 0
}

curl -X POST -u Administrator:password \
      http://localhost:8091/pools/default/buckets/user_sessions \
      -d maxTTL=7200

curl -s -X GET -u Administrator:password \
      http://localhost:8091/pools/default/buckets/user_sessions \
      | jq '{maxTTL: .maxTTL}'
{
  "maxTTL": 7200
}

See Creating and Editing Buckets for more about editing buckets.

You can only set the maxTTL of a collection when creating it. The following example creates a collection named test_site in the store scope of the user_sessions bucket and sets its maxTTL to 1 hour:

curl -s -X POST -u Administrator:password \
     http://localhost:8091/pools/default/buckets/user_sessions/scopes/store/collections \
     -d name=test_site \
     -d maxTTL=3600

{"uid":"5"}

curl -s -X GET -u Administrator:password \
     http://localhost:8091/pools/default/buckets/user_sessions/scopes \
     | jq ' .scopes[].collections | map(select(.name == "test_site"))'

[
  {
    "name": "test_site",
    "uid": "a",
    "maxTTL": 3600,
    "history": false
  }
]
[]

See rest-api/creating-a-collection.adoc for more information about creating collections via the REST-API.

Set maxTTL Using the Command Line Tools and SDKs

You can set maxTTL for collections and buckets using the CLI and SDK.

With the couchbase-cli tool, you can set maxTTL using the bucket-create, bucket-edit, and collection-manage commands.

When using the SDKs, look for maxTTL or maxExpiry options. For example, the NodeJS SDK IBucketSettings interface has a maxExpiry property.