Document.TimeToLive Property

Definition

Gets or sets the time to live in seconds of the document in the Azure DocumentDB database service.

[Newtonsoft.Json.JsonProperty(NullValueHandling=Newtonsoft.Json.NullValueHandling.Ignore, PropertyName="ttl")]
public Nullable<int> TimeToLive { get; set; }
Property Value

It is an optional property. A valid value must be either a nonzero positive integer, '-1', or null. By default, TimeToLive is set to null meaning the document inherits the collection's DefaultTimeToLive. The unit of measurement is seconds. The maximum allowed value is 2147483647. When the value is '-1', it means never expire regardless of the collection's DefaultTimeToLive value.

Remarks

The final time-to-live policy of a document is evaluated after consulting the collection's DefaultTimeToLive.

When the TimeToLive is null, the document inherits the collection's DefaultTimeToLive. If the collection's DefaultTimeToLive is a nonzero positive integer, then the document will inherit that value as its time-to-live in seconds, and will be expired after the default time-to-live in seconds since its last write time. The expired documents will be deleted in background. Otherwise, the document will never expire.

When the TimeToLive is '-1', the document will never expire regardless of the collection's DefaultTimeToLive value.

When the TimeToLive is a nonzero positive integer, need to check the collection's DefaultTimeToLive. If the collection's DefaultTimeToLive is null, which means the time-to-live has been turned off on the collection, and the document's TimeToLive should be disregarded and the document will never expire. Otherwise, the document's TimeToLive will be honored. The document will be expired after the default time-to-live in seconds since its last write time. The expired documents will be deleted in background.

The table below shows an example of the matrix to evaluate the final time-to-live policy given a collection's DefaultTimeToLive and a document's TimeToLive.

CollectionMatrix
DefaultTimeToLive = null
DocumentResult
TimeToLive = nullTTL is disabled. The document will never expire (default).
TimeToLive = -1TTL is disabled. The document will never expire.
TimeToLive = 2000TTL is disabled. The document will never expire.
DefaultTimeToLive = -1
DocumentResult
TimeToLive = nullTTL is enabled. The document will never expire (default).
TimeToLive = -1TTL is enabled. The document will never expire.
TimeToLive = 2000TTL is enabled. The document will expire after 2000 seconds.
DefaultTimeToLive = 1000
DocumentResult
TimeToLive = nullTTL is enabled. The document will expire after 1000 seconds (default).
TimeToLive = -1TTL is enabled. The document will never expire.
TimeToLive = 2000TTL is enabled. The document will expire after 2000 seconds.