Azure Cosmos DB 中的生存时间 (TTL)Time to Live (TTL) in Azure Cosmos DB

利用生存时间(简称 TTL),Azure Cosmos DB 能够在特定一段时间后自动将项从容器中删除。With Time to Live or TTL, Azure Cosmos DB provides the ability to delete items automatically from a container after a certain time period. 默认情况下,可以在容器级别设置生存时间,并基于每个项替代该值。By default, you can set time to live at the container level and override the value on a per-item basis. 在容器或项级别设置 TTL 后,Azure Cosmos DB 会在一段时间(自上次修改项的时间开始算起)后自动删除这些项。After you set the TTL at a container or at an item level, Azure Cosmos DB will automatically remove these items after the time period, since the time they were last modified. 配置的生存时间值以秒为单位。Time to live value is configured in seconds. 配置 TTL 后,系统会基于 TTL 值自动删除已过期的项,不需要客户端应用程序显式发出的 delete 操作。When you configure TTL, the system will automatically delete the expired items based on the TTL value, without needing a delete operation that is explicitly issued by the client application.

删除过期项是一个后台任务,它使用剩余的请求单元,即用户请求没有使用的请求单元。Deletion of expired items is a background task that consumes left-over Request Units, that is Request Units that haven't been consumed by user requests. 即使在 TTL 过期后,如果容器出现请求过载的情况,并且没有足够的 RU 使用,也会延迟数据删除操作。Even after the TTL has expired, if the container is overloaded with requests and if there aren't enough RU's available, the data deletion is delayed. 如果提供了足够的 RU 来执行删除操作,则会删除数据。Data is deleted once there are enough RUs available to perform the delete operation. 虽然数据删除延迟,但任何查询都不会(通过任何 API)在 TTL 已过期后返回数据。Though the data deletion is delayed, data is not returned by any queries (by any API) after the TTL has expired.

容器和项的生存时间Time to live for containers and items

生存时间值是以秒为单位设置的,解释为自上次修改项的时间的增量。The time to live value is set in seconds, and it is interpreted as a delta from the time that an item was last modified. 可以针对容器或容器中的项设置生存时间:You can set time to live on a container or an item within the container:

  1. 容器的生存时间(使用 DefaultTimeToLive 设置):Time to Live on a container (set using DefaultTimeToLive):

    • 如果缺失(或设置为 null),则项不会自动过期。If missing (or set to null), items are not expired automatically.

    • 如果存在且值设置为“-1”(无限期),则默认情况下,项不会过期。If present and the value is set to "-1", it is equal to infinity, and items don't expire by default.

    • 如果存在且值设置为某个数字(“n”),则项将在上次修改“n”秒后过期。 If present and the value is set to some number "n" - items will expire "n" seconds after their last modified time.

  2. 项的生存时间(使用 ttl 设置):Time to Live on an item (set using ttl):

    • 仅当父容器的 DefaultTimeToLive 存在且不是设置为 null 时,此属性才适用。This Property is applicable only if DefaultTimeToLive is present and it is not set to null for the parent container.

    • 如果存在,它将替代父容器的 DefaultTimeToLive 值。If present, it overrides the DefaultTimeToLive value of the parent container.

生存时间配置Time to Live configurations

  • 如果将某个容器的 TTL 设置为“n”,该容器中的项将在 n 秒后过期。 If TTL is set to "n" on a container, then the items in that container will expire after n seconds. 如果同一容器中的项有自身的生存时间且 TTL 设置为 -1(表示不会过期),或者某些项使用不同的数字替代了生存时间设置,则这些项会根据其自己的已配置 TTL 值过期。If there are items in the same container that have their own time to live, set to -1 (indicating they do not expire) or if some items have overridden the time to live setting with a different number, these items expire based on their own configured TTL value.

  • 如果未针对某个容器设置 TTL,则此容器中的项的生存时间不起作用。If TTL is not set on a container, then the time to live on an item in this container has no effect.

  • 如果某个容器的 TTL 设置为 -1,则此容器中生存时间设置为 n 的项将在 n 秒后过期,剩余的项不会过期。If TTL on a container is set to -1, an item in this container that has the time to live set to n, will expire after n seconds, and remaining items will not expire.

基于 TTL 删除项是免费的。Deleting items based on TTL is free. TTL 过期后删除项不会产生额外的费用(即,不会消耗额外的 RU)。There is no additional cost (that is, no additional RUs are consumed) when item is deleted as a result of TTL expiration.

示例Examples

本部分显示分配给容器和项不同生存时间值的一些示例:This section shows some examples with different time to live values assigned to container and items:

示例 1Example 1

容器的 TTL 设置为 null (DefaultTimeToLive = null)TTL on container is set to null (DefaultTimeToLive = null)

项的 TTLTTL on item 结果Result
ttl = nullttl = null TTL 已禁用。TTL is disabled. 该项将永不过期(默认值)。The item will never expire (default).
ttl = -1ttl = -1 TTL 已禁用。TTL is disabled. 该项将永不过期。The item will never expire.
ttl = 2000ttl = 2000 TTL 已禁用。TTL is disabled. 该项将永不过期。The item will never expire.

示例 2Example 2

容器的 TTL 设置为 -1 (DefaultTimeToLive = -1)TTL on container is set to -1 (DefaultTimeToLive = -1)

项的 TTLTTL on item 结果Result
ttl = nullttl = null TTL 已启用。TTL is enabled. 该项将永不过期(默认值)。The item will never expire (default).
ttl = -1ttl = -1 TTL 已启用。TTL is enabled. 该项将永不过期。The item will never expire.
ttl = 2000ttl = 2000 TTL 已启用。TTL is enabled. 该项将在 2000 秒后过期。The item will expire after 2000 seconds.

示例 3Example 3

容器的 TTL 设置为 1000 (DefaultTimeToLive = 1000)TTL on container is set to 1000 (DefaultTimeToLive = 1000)

项的 TTLTTL on item 结果Result
ttl = nullttl = null TTL 已启用。TTL is enabled. 该项将在 1000 秒(默认值)后过期。The item will expire after 1000 seconds (default).
ttl = -1ttl = -1 TTL 已启用。TTL is enabled. 该项将永不过期。The item will never expire.
ttl = 2000ttl = 2000 TTL 已启用。TTL is enabled. 该项将在 2000 秒后过期。The item will expire after 2000 seconds.

后续步骤Next steps

通过以下文章了解如何配置生存时间:Learn how to configure Time to Live in the following articles: