Configure and manage Time to Live in Azure Cosmos DB (2024)

APPLIES TO: NoSQL

In Azure Cosmos DB, you can choose to configure Time to Live (TTL) at the container level, or you can override it at an item level after setting for the container. You can configure TTL for a container by using Azure portal or the language-specific SDKs. Item level TTL overrides can be configured by using the SDKs.

This article's content is related to Azure Cosmos DB transactional store TTL. If you are looking for analitycal store TTL, that enables NoETL HTAP scenarios through Azure Synapse Link, please click here.

Enable time to live on a container using the Azure portal

Use the following steps to enable time to live on a container with no expiration. Enabling TTL at the container level to allow the same value to be overridden at an individual item's level. You can also set the TTL by entering a non-zero value for seconds.

1. Sign in to the Azure portal.

2. Create a new Azure Cosmos DB account or select an existing account.

   See Also

   Expire data in Azure Cosmos DB with Time to LiveExpire Data from Collections by Setting TTLMigrating to Azure Cosmos DB with Mongo API: 5 Things to KnowManage indexing in Azure Cosmos DB for MongoDB

3. Open the Data Explorer pane.

4. Select an existing container, expand the Settings tab and modify the following values:

   • Under Setting find, Time to Live.

   • Based on your requirement, you can:

     • Turn off this setting
     • Set it to On (no default) or
     • Turn On with a TTL value specified in seconds.

   • Select Save to save the changes.

   

• When DefaultTimeToLive is null, then your Time to Live is Off
• When DefaultTimeToLive is -1 then, your Time to Live setting is On (No default)
• When DefaultTimeToLive has any other Int value (except 0), then your Time to Live setting is On. The server will automatically delete items based on the configured value.

Enable time to live on a container using Azure CLI or Azure PowerShell

To create or enable TTL on a container see,

• Create a container with TTL using Azure CLI
• Create a container with TTL using PowerShell

Enable time to live on a container using an SDK

Database database = client.GetDatabase("database");ContainerProperties properties = new (){ Id = "container", PartitionKeyPath = "/customerId", // Never expire by default DefaultTimeToLive = -1};// Create a new container with TTL enabled and without any expiration valueContainer container = await database .CreateContainerAsync(properties);

Set time to live on a container using an SDK

To set the time to live on a container, you need to provide a non-zero positive number that indicates the time period in seconds. Based on the configured TTL value, all items in the container after the last modified timestamp of the item _ts are deleted.

Database database = client.GetDatabase("database");ContainerProperties properties = new (){ Id = "container", PartitionKeyPath = "/customerId", // Expire all documents after 90 days DefaultTimeToLive = 90 * 60 * 60 * 24};// Create a new container with TTL enabled and without any expiration valueContainer container = await database .CreateContainerAsync(properties);

Set time to live on an item using the Portal

In addition to setting a default time to live on a container, you can set a time to live for an item. Setting time to live at the item level will override the default TTL of the item in that container.

• To set the TTL on an item, you need to provide a non-zero positive number, which indicates the period, in seconds, to expire the item after the last modified timestamp of the item _ts. You can provide a -1 as well when the item shouldn't expire.

• If the item doesn't have a TTL field, then by default, the TTL set to the container will apply to the item.

• If TTL is disabled at the container level, the TTL field on the item will be ignored until TTL is re-enabled on the container.

Use the following steps to enable time to live on an item:

1. Sign in to the Azure portal.

2. Create a new Azure Cosmos DB account or select an existing account.

3. Open the Data Explorer pane.

4. Select an existing container, expand it and modify the following values:

   • Open the Scale & Settings window.
   • Under Setting find, Time to Live.
   • Select On (no default) or select On and set a TTL value.
   • Select Save to save the changes.

5. Next navigate to the item for which you want to set time to live, add the ttl property and select Update.

   { "id": "1", "_rid": "Jic9ANWdO-EFAAAAAAAAAA==", "_self": "dbs/Jic9AA==/colls/Jic9ANWdO-E=/docs/Jic9ANWdO-EFAAAAAAAAAA==/", "_etag": "\"0d00b23f-0000-0000-0000-5c7712e80000\"", "_attachments": "attachments/", "ttl": 10, "_ts": 1551307496}

Set time to live on an item using an SDK

public record SalesOrder(string id, string customerId, int ttl);

Container container = database.GetContainer("container");SalesOrder item = new ( "SO05", "CO18009186470" // Expire sales order in 30 days using "ttl" property ttl: 60 * 60 * 24 * 30);await container.CreateItemAsync<SalesOrder>(item);

Reset time to live using an SDK

You can reset the time to live on an item by performing a write or update operation on the item. The write or update operation will set the _ts to the current time, and the TTL for the item to expire will begin again. If you wish to change the TTL of an item, you can update the field just as you update any other field.

SalesOrder item = await container.ReadItemAsync<SalesOrder>( "SO05", new PartitionKey("CO18009186470"));// Update ttl to 2 hoursSalesOrder modifiedItem = item with { ttl = 60 * 60 * 2 };await container.ReplaceItemAsync<SalesOrder>( modifiedItem, "SO05", new PartitionKey("CO18009186470") );

Disable time to live using an SDK

To disable time to live on a container and stop the background process from checking for expired items, the DefaultTimeToLive property on the container should be deleted. Deleting this property is different from setting it to -1. When you set it to -1, new items added to the container will live forever, however you can override this value on specific items in the container. When you remove the TTL property from the container the items will never expire, even if they have explicitly overridden the previous default TTL value.

ContainerProperties properties = await container.ReadContainerAsync();// Disable ttl at container-levelproperties.DefaultTimeToLive = null;await container.ReplaceContainerAsync(properties);

Next steps

Learn more about time to live in the following article:

• Time to live