Document.TimeToLive Property

Definition

Namespace:

Microsoft.Azure.Documents

Assemblies:

Microsoft.Azure.DocumentDB.Core.dll, Microsoft.Azure.Documents.Client.dll

Packages:

Microsoft.Azure.DocumentDB v2.18.0, Microsoft.Azure.DocumentDB.Core v2.18.0

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

Nullable<Int32>

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.

Collection	Matrix
DefaultTimeToLive = null	Document Result TimeToLive = null TTL is disabled. The document will never expire (default). TimeToLive = -1 TTL is disabled. The document will never expire. TimeToLive = 2000 TTL is disabled. The document will never expire.
DefaultTimeToLive = -1	Document Result TimeToLive = null TTL is enabled. The document will never expire (default). TimeToLive = -1 TTL is enabled. The document will never expire. TimeToLive = 2000 TTL is enabled. The document will expire after 2000 seconds.
DefaultTimeToLive = 1000	Document Result TimeToLive = null TTL is enabled. The document will expire after 1000 seconds (default). TimeToLive = -1 TTL is enabled. The document will never expire. TimeToLive = 2000 TTL is enabled. The document will expire after 2000 seconds.

See also

• DocumentCollection