使用 TTL 索引管理数据保留

使用 TTL 索引管理数据保留

本页面介绍了如何使用 MongoDB API、 Google Cloud 控制台和 Google Cloud CLI 来配置存留时间 (TTL) 索引。

存留时间概览

使用 TTL 索引来自动移除数据库中的过时数据。TTL 索引将给定字段指定为给定集合中的文档的到期时间。借助 TTL，您可以清除过时的数据，从而降低存储费用。数据通常会在失效时间后的 24 小时内删除。

价格

TTL 删除操作会使用代管式删除单元。如需了解价格，请参阅 Firestore 企业版价格。

限制和约束

• 您只能为每个集合创建一个 TTL 索引。
• 您最多可以有 500 个 TTL 索引。

TTL 删除操作

请注意 TTL 驱动的删除操作的以下关键行为：

• 通过 TTL 执行的删除操作不是即时进程。已到期的文档会继续显示在查询和查找请求中，直到 TTL 进程实际删除它们为止。TTL 以删除操作的及时性为代价来降低删除操作的总拥有成本。数据通常会在到期时间后的 24 小时内删除。

• 为现有集合创建 TTL 索引会导致系统根据新的 TTL 索引批量删除到期的所有数据。请注意，此批量删除操作也不是即时的，并且取决于该集合的数据量。

• 如果文档具有过去的到期时间，并且您向集合添加了新的 TTL 索引，则该文档将在 TTL 索引完成设置并变为活跃状态后的 24 小时内删除。

• TTL 不一定会按照与文档到期时间戳相同的顺序删除文档。

• 删除操作不是以事务方式执行的。到期时间相同的文档不一定会同时删除。如果您需要这样做，请使用客户端库执行删除操作。

• 与 MongoDB 兼容的 Firestore 始终根据最新的 TTL 字段来确定到期时间。例如，如果某个已过期但尚未删除的文档的 TTL 字段更新为较晚的日期，则该文档将恢复为未过期状态，并且系统将使用新的日期。

• 只有在 TTL 字段设置为 Date and time/BSON Date 值或设置为包含 Date and time/BSON Date 值的 Array 值时，与 MongoDB 兼容的 Firestore 才会对文档应用相应的到期时间。如果将某个文档的此字段留空或设置为 null 之类的值，则可停用该文档的到期时间设置。

• TTL 的设计能够最大限度地减少对其他数据库活动的影响。TTL 驱动的删除操作被视为具有较低优先级。我们还提供了其他策略，用于消除由 TTL 驱动的删除操作导致的流量高峰。

与 TTL 索引的区别

与其他 Firestore 索引不同，TTL 索引在查询规划期间不会用于提升性能。如需提高使用 TTL 的字段的查询性能，您必须将其添加到单独的非 TTL 索引中。

请务必注意，由于 TTL 字段使用时间戳，因此将它们添加到非 TTL 索引可能会导致热点。当写入和删除操作以高速率集中在窄范围的文档中时，就会出现热点，这可能会在写入流量高峰期对伸缩性能产生负面影响。

权限

创建或删除 TTL 索引的主账号需要项目的以下权限：

• 查看 TTL 索引需要 datastore.indexes.list 和 datastore.indexes.get 权限。
• 创建或删除 TTL 索引需要 datastore.indexes.update 权限。
• 检查 TTL 操作的状态需要 datastore.operations.list 和 datastore.operations.get 权限。

如需了解拥有这些权限的角色，请参阅 Firestore Identity and Access Management 角色。

创建 TTL 索引

创建 TTL 索引时，您可以将某个文档字段指定为集合中文档的到期时间。

TTL 使用指定的字段来识别符合删除条件的文档。TTL 字段必须设置为 Timestamp/BSON Date 值或设置为包含 Timestamp/BSON Date 值的 Array 值。您可以选择现有的字段，也可以指定您打算稍后添加的字段。

注意：在 2026 年 2 月之前创建的某些 TTL 索引不适用于 Array 值内的 Timestamp/BSON Date 值。如需更新 TTL 索引以应用于 Array 值，请删除并重新创建索引。

在设置 TTL 字段值之前，请注意以下事项：

• TTL 字段值可以是将来、现在或过去的时间。如果值为过去的时间，则文档直接符合删除条件。例如，您可以创建包含字段 expireAt 的 TTL 索引，然后将该索引添加到现有文档中。

• 若对某个文档使用任何其他数据类型或是不为其设置 TTL 字段值，都会停用该文档的 TTL 功能。

如需创建 TTL 索引，请按照以下步骤操作：

MongoDB API

在调用 createIndex() 方法时添加 expireAfterSeconds 索引选项：

db.COLLECTION_NAME.createIndex({"TTL_FIELD": 1, "expireAfterSeconds": EXPIRATION_OFFSET_SECONDS})

例如：

db.restaurants.createIndex({"ts": 1, "expireAfterSeconds": 3600})

expireAfterSeconds 将 TTL 标识为 TTL 索引，并且是 TTL 字段中的时间戳值与到期时间之间的偏移量。如果 expireAfterSeconds 设置为 0，则到期时间直接由 TTL 字段中的时间戳值给出。

注意以下限制：

• TTL 索引必须仅包含一个字段。
• TTL 索引不会用于查询规划，也不会提高查询的性能。
• 您只能为每个集合创建一个 TTL 索引。
• 通过 MongoDB API 创建 TTL 索引的审核日志使用方法名称 google.firestore.admin.v1.FirestoreAdmin.UpdateField。

Google Cloud Console

1. 在 Google Cloud 控制台中，前往数据库页面。

   前往“数据库”

2. 从数据库列表中选择所需的数据库。

3. 在导航菜单中，点击存留时间 (TTL)。

4. 点击创建政策。

5. 输入集合名称和时间戳字段名称。

6. 点击创建。

控制台会返回到 Time-to-live（存留时间）页面。如果操作成功开始，则页面会在 TTL 索引表中添加一个条目。如果失败，则页面会显示错误消息。

gcloud

1. 在 Google Cloud 控制台中，激活 Cloud Shell。

   激活 Cloud Shell

   Cloud Shell 会话随即会在 Google Cloud 控制台的底部启动，并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。

2. 使用 firestore fields ttls update 命令配置 TTL 索引。添加 --async 标志可阻止 gcloud CLI 等待操作完成。

    gcloud firestore fields ttls update
   ttl_field --collection-group=collection_name
   --enable-ttl 

TTL 索引创建时长

创建 TTL 索引至少需要十分钟或更长时间。操作一旦启动就无法通过关闭终端来取消。

查看 TTL 索引

如需查看 TTL 索引，请按照以下步骤操作：

MongoDB API

使用 listIndexes() 方法查看 TTL 索引。例如：

db.restaurants.listIndexes()

请注意，输出将包含 TTL 索引和非 TTL 索引。TTL 索引将包含 expireAfterSeconds 选项。

Google Cloud Console

1. 在 Google Cloud 控制台中，前往数据库页面。

   前往“数据库”

2. 从数据库列表中选择所需的数据库。

3. 在导航菜单中，点击存留时间 (TTL)。

控制台会列出数据库的 TTL 索引以及每个索引的状态。

gcloud

1. 在 Google Cloud 控制台中，激活 Cloud Shell。

   激活 Cloud Shell

   Cloud Shell 会话随即会在 Google Cloud 控制台的底部启动，并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。

2. 使用 firestore fields ttls list 命令配置 TTL 索引。以下命令会列出所有 TTL 索引。

   gcloud firestore fields ttls list
   

   如需列出特定集合下的 TTL 索引，请使用以下命令：

   gcloud firestore fields ttls list  --collection-group=collection_name
   

查看操作详细信息

您可以使用 gcloud CLI 查看有关处于 CREATING 状态的 TTL 索引的更多详细信息。

使用 operations list 命令可以查看所有正在运行和最近完成的操作：

gcloud firestore operations list

响应包含操作的进度估计值。

删除 TTL 索引

如需删除 TTL 索引，请按照以下步骤操作：

MongoDB API

使用 dropIndex() 方法删除 TTL 索引。例如：

使用索引名称删除 TTL 索引

db.restaurants.dropIndex("ts_1")

使用索引定义删除 TTL 索引

db.restaurants.dropIndex({"ts": 1})

请注意，通过 MongoDB API 删除 TTL 索引的审核日志使用方法名称 google.firestore.admin.v1.FirestoreAdmin.UpdateField。

注意：使用 MongoDB drop() 命令删除集合会自动移除为该集合配置的 TTL 索引。Drop Collection 目前处于预览版阶段。

Google Cloud Console

1. 在 Google Cloud 控制台中，前往数据库页面。

   前往“数据库”

2. 从数据库列表中选择所需的数据库。

3. 在导航菜单中，点击存留时间 (TTL)。

4. 在 TTL 索引表中，找到相应 TTL 索引所在的行。在此表行中，点击删除（垃圾桶）按钮。

5. 点击删除以确认。

控制台会返回到 Time-to-live（存留时间）页面。如果成功，则与 MongoDB 兼容的 Firestore 会从表中移除 TTL 索引。

gcloud

1. 在 Google Cloud 控制台中，激活 Cloud Shell。

   激活 Cloud Shell

   Cloud Shell 会话随即会在 Google Cloud 控制台的底部启动，并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。

2. 使用 firestore fields ttls update 命令配置 TTL 索引。添加 --async 标志可阻止 gcloud CLI 等待操作完成。

   gcloud firestore fields ttls update ttl_field --collection-group=collection_name --disable-ttl
   

监控 TTL 删除操作

您可以使用 Cloud Monitoring 查看有关 TTL 驱动的删除操作的指标。与 MongoDB 兼容的 Firestore 提供以下 TTL 指标：

指标类型	指标名称	指标说明
firestore.googleapis.com/document/ttl_deletion_count	存留时间删除操作计数	TTL 索引删除的文档总数。
firestore.googleapis.com/document/ttl_expiration_to_deletion_delays	存留时间到期到删除延迟	文档根据 TTL 索引到期与实际删除之间的间隔时间。

如需使用与 MongoDB 兼容的 Firestore 指标设置信息中心，请参阅管理自定义信息中心以及添加信息中心 widget。