在 Azure Cosmos DB 中配置生存时间

项目
06/08/2023

适用范围： NoSQL

在 Azure Cosmos DB 中，可以选择在容器级别配置生存时间 (TTL)，也可以在为容器完成设置之后，在项级别重写生存时间。可以通过 Azure 门户或特定于语言的 SDK 配置容器的 TTL。可以通过 SDK 配置项级别 TTL 重写。

本文的内容与 Azure Cosmos DB 事务存储 TTL 相关。如果正在查找通过 Azure Synapse Link 启用 NoETL HTAP 方案的分析存储 TTL，请单击此处。

使用 Azure 门户在容器上启用生存时间

通过以下步骤在没有到期时间的容器上启用生存时间。在容器级别启用 TTL，以允许在单个项的级别重写相同的值。也可通过输入非零值（代表秒）来设置 TTL。

登录到 Azure 门户。
创建新的 Azure Cosmos DB 帐户或选择现有的帐户。
打开“数据资源管理器”窗格。
选择一个现有的容器，展开“设置”选项卡并修改以下值：
- 在“设置”下找到“生存时间”。
- 根据需求，可以：
  - 关闭此设置
  - 将其设置为“开(无默认设置)”或
  - 使用以秒为单位指定的 TTL 值打开。
- 选择“保存”，保存更改。

当 DefaultTimeToLive 为 null 时，生存时间为“关”
当 DefaultTimeToLive 为 -1 时，“生存时间”设置为“开”（无默认值）
当 DefaultTimeToLive 具有任何其他整数值（0 除外）时，“生存时间”设置为“开”。服务器将基于配置的值自动删除项。

使用 Azure CLI 或 Azure PowerShell 在容器上启用生存时间

若要在容器上创建或启用 TTL，请参阅

使用 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);

CosmosDatabase database = client.getDatabase("database");

CosmosContainerProperties properties = new CosmosContainerProperties(
    "container",
    "/customerId"
);
// Never expire by default
properties.setDefaultTimeToLiveInSeconds(-1);

// Create a new container with TTL enabled and without any expiration value
CosmosContainerResponse response = database
    .createContainerIfNotExists(properties);

const database = await client.database("database");

const properties = {
    id: "container",
    partitionKey: "/customerId",
    // Never expire by default
    defaultTtl: -1
};

const { container } = await database.containers
    .createIfNotExists(properties);

database = client.get_database_client('database')

database.create_container(
    id='container',
    partition_key=PartitionKey(path='/customerId'),
    # Never expire by default
    default_ttl=-1
)

使用 SDK 在容器上设置生存时间

若要在容器上设置生存时间，需提供一个非零正数来指示时间段（以秒为单位）。在项的上次修改的时间戳 (_ts) 过后，将会删除容器中的所有值，具体取决于配置的 TTL 值。

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);

CosmosDatabase database = client.getDatabase("database");

CosmosContainerProperties properties = new CosmosContainerProperties(
    "container",
    "/customerId"
);
// Expire all documents after 90 days
properties.setDefaultTimeToLiveInSeconds(90 * 60 * 60 * 24);

CosmosContainerResponse response = database
    .createContainerIfNotExists(properties);

const database = await client.database("database");

const properties = {
    id: "container",
    partitionKey: "/customerId",
    // Expire all documents after 90 days
    defaultTtl: 90 * 60 * 60 * 24
};

const { container } = await database.containers
    .createIfNotExists(properties);

database = client.get_database_client('database')

database.create_container(
    id='container',
    partition_key=PartitionKey(path='/customerId'),
    # Expire all documents after 90 days
    default_ttl=90 * 60 * 60 * 24
)

使用门户设置项目生存时间

除了在容器上设置默认的生存时间，还可以为项设置生存时间。在项级别设置生存时间将重写该容器中项的默认 TTL。

若要在项上设置 TTL，则需要提供一个非零正数，该数字表示自项上次的修改时间戳 (_ts) 之后，项过期所经过的时间段（以秒为单位）。当项目不应过期时，你也可以提供 -1。
如果项没有 TTL 字段，则默认情况下，设置到容器的 TTL 将应用到项。
如果在容器级别禁用了 TTL，在项上的 TTL 字段会被忽略，直到在容器上再次启用 TTL。

通过以下步骤在项上启用生存时间：

登录到 Azure 门户。
创建新的 Azure Cosmos DB 帐户或选择现有的帐户。
打开“数据资源管理器”窗格。
选择一个现有的容器，将其展开并修改以下值：
- 打开“规模和设置”窗口。
- 在“设置”下找到“生存时间”。
- 选择“启用(无默认值)”或选择“启用”，然后设置一个 TTL 值。
- 选择“保存”，保存更改。

接下来导航到要为其设置生存时间的项，添加 ttl 属性，然后选择“更新”。

{
    "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
}

使用 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);

public class SalesOrder {

    public String id;

    public String customerId;

    // Include a property that serializes to "ttl" in JSON
    public Integer ttl;

}

CosmosContainer container = database.getContainer("container");

SalesOrder item = new SalesOrder();
item.id = "SO05";
item.customerId = "CO18009186470";
// Expire sales order in 30 days using "ttl" property
item.ttl = 60 * 60 * 24 * 30;

container.createItem(item);

const container = await database.container("container");

const item = {
    id: 'SO05',
    customerId: 'CO18009186470',
    // Expire sales order in 30 days using "ttl" property
    ttl: 60 * 60 * 24 * 30
};

await container.items.create(item);

container = database.get_container_client('container')

item = {
    'id': 'SO05',
    'customerId': 'CO18009186470',
    # Expire sales order in 30 days using "ttl" property
    'ttl': 60 * 60 * 24 * 30
}

container.create_item(body=item)

使用 SDK 重置生存时间

可以通过在项上执行写入或更新操作，重置项的生存时间。写入或更新操作会将 _ts 设置为当前时间，要到期的项的 TTL 就会重启。若要更改项的 TTL，可以更新相关字段，就像更新任何其他字段那样。

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")    
);

CosmosItemResponse<SalesOrder> response = container.readItem(
    "SO05", 
    new PartitionKey("CO18009186470"),
    SalesOrder.class
);

SalesOrder item = response.getItem();

// Update ttl to 2 hours
item.ttl = 60 * 60 * 2;

CosmosItemRequestOptions options = new CosmosItemRequestOptions();
container.replaceItem(
    item,
    "SO05", 
    new PartitionKey("CO18009186470"),
    options
);

const { resource: item } = await container.item(
    'SO05',
    'CO18009186470'
).read();

// Update ttl to 2 hours
item.ttl = 60 * 60 * 2;

await container.item(
    'SO05',
    'CO18009186470'
).replace(item);

item = container.read_item(
    item='SO05',
    partition_key='CO18009186470'
)

# Update ttl to 2 hours
item['ttl'] = 60 * 60 * 2 

container.replace_item(
    item='SO05',
    body=item
)

使用 SDK 禁用生存时间

若要在容器上禁用生存时间并阻止后台进程查找过期项，则应删除容器上的 DefaultTimeToLive 属性。删除此属性不同于将其设置为 -1。将它设置为 -1 时，添加到容器的新项将永久生存。但是，可以在容器中的特定项上重写此值。从容器中删除 TTL 属性后项将永不会过期，即使这些项已显式重写了以前的默认 TTL 值。

ContainerProperties properties = await container.ReadContainerAsync();

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

await container.ReplaceContainerAsync(properties);

CosmosContainerResponse response = container.read();
CosmosContainerProperties properties = response.getProperties();

// Disable ttl at container-level
properties.setDefaultTimeToLiveInSeconds(null);

container.replace(properties);

const { resource: definition } = await container.read();

// Disable ttl at container-level
definition.defaultTtl = null;

await container.replace(definition);

database.replace_container(
    container,
    partition_key=PartitionKey(path='/id'),
    # Disable ttl at container-level
    default_ttl=None
)

后续步骤

在以下文章中详细了解生存时间：

生存时间

通过