Edit

Share via


Configure time to live in Azure Cosmos DB

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 TTL for the container. You can configure TTL for a container by using the Azure portal or the language-specific SDKs. Item-level TTL overrides can be configured by using the SDKs.

Tip

This article's content is related to Azure Cosmos DB transactional store TTL. If you're looking for analytical store TTL, which enables NoETL HTAP scenarios through Azure Synapse Link, see Analytical Time-to-Live.

Enable TTL on a container by using the Azure portal

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

  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 the Settings tab, and modify the following values:

    1. Under Settings, find Time to Live.
    2. Based on your requirement, you can:
    • Turn off this setting.
    • Set it to On (no default).
    • Turn On with a TTL value specified in seconds.
    1. Select Save to save the changes.

    Screenshot of the settings to configure Time to live in the Azure portal.

  • When DefaultTimeToLive is null, then your TTL is Off.
  • When DefaultTimeToLive is -1 then, your TTL setting is On (No default).
  • When DefaultTimeToLive has any other integer value (except 0), then your TTL setting is On. The server automatically deletes items based on the configured value.

Enable TTL on a container by using Azure CLI or Azure PowerShell

To create or enable TTL on a container, see:

Enable TTL on a container by 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 value
Container container = await database
    .CreateContainerAsync(properties);

Set TTL on a container by using an SDK

To set the TTL on a container, you need to provide a nonzero 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 value
Container container = await database
    .CreateContainerAsync(properties);

Set TTL on an item by using the Azure portal

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

  • To set the TTL on an item, you need to provide a nonzero 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 applies to the item.

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

Use the following steps to enable TTL 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. 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 TTL on an item by 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 TTL by using an SDK

You can reset the TTL on an item by performing a write or update operation on the item. The write or update operation sets the _ts to the current time, and the TTL for the item to expire begins 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 hours
SalesOrder modifiedItem = item with { 
    ttl = 60 * 60 * 2 
};

await container.ReplaceItemAsync<SalesOrder>(
    modifiedItem,
    "SO05", 
    new PartitionKey("CO18009186470")    
);

Disable TTL by using an SDK

To disable TTL 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 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 never expire, even if they explicitly override the previous default TTL value.

ContainerProperties properties = await container.ReadContainerAsync();

// Disable ttl at container-level
properties.DefaultTimeToLive = null;

await container.ReplaceContainerAsync(properties);