Which subdocument operations change the document expiration date?

When I create documents, I set the “expiry” option to 3 days. However I have noticed in the past, that if I make changes to the document using a subdocument operation, the expiration date that is visible in the metadata tab (in couchbase console) is set to 0, which means those documents never expire.
I believe this was a bug that was solved in issue https://issues.couchbase.com/browse/MB-16239 .
My question is, using the Node JS SDK 3.2.4, which subdocument operations will reset the expiration date to 0, and which subdocument operations accept an options parameter where we can set an “expiry” attribute ?
For example, can I do collection.mutateIn(docId, […operations], {expiry: 60 * 60 * 24 * 3}) ?
If I do collection.lookupIn(docId, […operations]), will it reset the document expiration date to 0 ?

The behaviour I am looking for is : in case of a mutateIn operation, set a new expiration date in 3 days, but in case of a lookupIn operation, don’t change the expiry date.

I can’t answer with certainty for the SDK’s (I don’t do much work in this space) but make sure that you understand how TTLs/expiry work at the low level.

First, the use of TTL/expiry can be confusing if it is an absolute unix timestamp it is pretty straightforward in N1QL and most of our SDKs (number of seconds since epoch) is just what you pass it. But you can also pass a fairly small number less than 30 days it is an offset for more details refer to document-expiration . You also need to understand the “precedence” as disclosed in buckets:expiration

So no you shouldn’t need to to set a bucket TTL if you do then you will be subject to the following constraints (provided no documents exist with a TTL already set):

  • Above that of Bucket TTL, the item’s TTL is reduced to the value of Bucket TTL.
  • Below that of Bucket TTL, the item’s TTL is left unchanged.
  • 0, the item’s TTL is reset to the value of Bucket TTL.

Second, although the TTL in always in seconds on the doc (property “expiration” in its metadata) there can be further confusion as in languages like Node (e.g. JavaScript) the native Date construct is in milliseconds and thus it depends on the Language, API and/or SDK used to determine what you need to pass (seconds, or milliseconds, or some date object).

The following will insert a document into bucket “source” and then set a TTL to expire in 10 minutes.

# This is a Python 2.5 SDK example
from couchbase.cluster import Cluster
from couchbase.cluster import PasswordAuthenticator
import time
cluster = Cluster('couchbase://localhost:8091')
authenticator = PasswordAuthenticator('Administrator', 'password')
cb = cluster.open_bucket('source')
cb.upsert('SampleDocument2', {'a_key': 'a_value'})
cb.touch('SampleDocument2', ttl=10*60)


Jon Strabala
Principal Product Manager - Server‌

As far as I know, updating a document resets the expiration. This is true with all kinds of update operations: via sdk update/upsert, via n1ql update and also via mutateIn.
lookupIn should not remove the expiration, as it does not update the document but simply reads it

Yes, you can pass “expiry” in the options of a mutateIn to preserve the expiration (Collection | couchbase)

1 Like

One of the new features in Couchbase 7.0 is the ability to preserve an existing expiry when modifying a document via upsert, replace, or subdoc mutation.

If you’re using Couchbase 7 and Node.js SDK 3.2, you can set the “preserveExpiry” field to true in the UpsertOptions, ReplaceOptions, and MutateInOptions.

I had trouble finding an example in the documentation, but here’s the code change that added the feature to the SDK: https://review.couchbase.org/c/couchnode/+/157888/4/lib/collection.ts

Support for preserving expiry during a N1QL query is planned for Couchbase 7.1 and Node.js SDK 4.0



As others have mentioned, lookupIn never modifies the expiry.

MutateInOptions has an expiry field you can use to set the expiry on the document. The mutateIn method has an options parameter for passing the MutateInOptions.


Thanks everyone for the answers. Actually in the end I opened the node js sdk for couchbase in my text editor, and with the code comments and typescript typings I was able to figure out which parameters each method accepts including the “expiry” attribute.