Share via


Document.TimeToLive Property

Definition

Gets or sets the time to live in seconds of the document in the Azure Cosmos DB service.

[Newtonsoft.Json.JsonProperty(NullValueHandling=Newtonsoft.Json.NullValueHandling.Ignore, PropertyName="ttl")]
public int? TimeToLive { get; set; }
[<Newtonsoft.Json.JsonProperty(NullValueHandling=Newtonsoft.Json.NullValueHandling.Ignore, PropertyName="ttl")>]
member this.TimeToLive : Nullable<int> with get, set
Public Property TimeToLive As Nullable(Of Integer)

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.

Attributes
Newtonsoft.Json.JsonPropertyAttribute

Examples

The example below removes 'ttl' from document content. The document will inherit the collection's DefaultTimeToLive as its time-to-live value.

document.TimeToLive = null;

The example below ensures that the document should never expire regardless.

document.TimeToLive = -1;

The example below sets the time-to-live in seconds on a document. The document will expire after 1000 seconds since its last write time when the collection's DefaultTimeToLive is not null.

document.TimeToLive = 1000;

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.

Applies to

See also