使用 TTL 索引管理資料保留機制

本頁說明如何使用 MongoDB API、Google Cloud 控制台和 Google Cloud CLI 設定存留時間 (TTL) 索引。

存留時間總覽

使用 TTL 索引，自動從資料庫中移除過時資料。存留時間索引會將指定欄位設為指定集合中文件的到期時間。您可以使用 TTL 清除過時資料，藉此降低儲存空間成本。通常會在到期時間後的 24 小時內刪除資料。

定價

TTL 刪除作業會計入文件刪除費用。如要瞭解刪除作業的定價，請參閱 Cloud Firestore Enterprise 版定價。

限制和條件

  • 每個集合只能建立一個存留時間索引。
  • 您最多可以有 500 個 TTL 索引。

存留時間刪除

請注意下列 TTL 驅動刪除作業的主要行為：

  • 透過存留時間刪除資料並非立即生效，過期文件會繼續顯示在查詢和查閱要求中，直到 TTL 程序實際刪除文件為止。TTL 會犧牲刪除作業的及時性，以減少刪除作業的總持有成本。通常會在到期時間後的 24 小時內刪除資料。

  • 在現有集合上建立 TTL 索引，會導致系統根據新的 TTL 索引，大量刪除所有過期資料。請注意，大量刪除作業也需要時間，所需時間取決於該集合的資料量。

  • 如果文件已過期，且您在集合中新增 TTL 索引，系統會在 TTL 索引設定完成並啟用後的 24 小時內刪除文件。

  • TTL 不一定會按照文件到期時間戳記的順序刪除文件。

  • 刪除作業不會以交易方式進行。即使文件到期時間相同，也不一定會同時刪除。如要執行這項操作，請使用用戶端程式庫刪除資料。

  • Cloud Firestore 一律會採用最新的 TTL 欄位來判斷到期時間。舉例來說，如果已過期但尚未刪除的文件將存留時間欄位更新為較晚的日期，該文件就不會過期，系統會使用新的日期。

  • 只有在 TTL 欄位設為 Date and time/BSON Date 值或包含 Date and time/BSON Date 值的 Array 值時，Cloud Firestore 才會讓文件過期。如要個別停用文件到期日，請將欄位留空或設為 null 等值。

  • 存留時間的設計宗旨是盡量減少對其他資料庫活動的影響。系統會以較低的優先順序處理因 TTL 而刪除的資料。此外，我們也採取其他策略，以平緩存留時間驅動刪除作業造成的流量尖峰。

存留時間欄位和非存留時間索引

存留時間欄位可建立索引或不建立索引。不過，由於 TTL 欄位是時間戳記，因此在非 TTL 索引中加入該欄位，可能會影響較高流量速率的效能。在非 TTL 索引中加入時間戳記欄位可能會建立熱點，這違反最佳做法。熱點是指對小範圍文件進行高速讀取、寫入和刪除作業。

權限

建立或捨棄 TTL 索引的主體必須具備專案中的下列權限：

  • 如要查看 TTL 索引，必須具備 datastore.indexes.list 和 datastore.indexes.get 權限。
  • 建立或捨棄 TTL 索引需要 datastore.indexes.update 權限。
  • 如要查看 TTL 作業的狀態，必須使用 datastore.operations.list 和 datastore.operations.get。

如要瞭解指派這些權限的角色，請參閱「Cloud Firestore 身分與存取權管理角色」。

事前準備

使用 gcloud CLI 管理 TTL 索引前，請先使用 gcloud components update 指令將元件更新至最新可用版本：

gcloud components update

建立存留時間索引

建立存留時間索引時，請將文件欄位指定為集合中文件的到期時間。

存留時間會使用指定欄位，識別符合刪除條件的文件。 TTL 欄位必須設為 Timestamp/BSON Date 值，或包含 Timestamp/BSON Date 值的 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 索引無法用於查詢。
  • 每個集合只能建立一個存留時間索引。
  • 使用 MongoDB API 建立 TTL 索引的稽核記錄會使用 google.firestore.admin.v1.FirestoreAdmin.UpdateField 方法名稱。

Google Cloud Console

  1. 前往 Google Cloud 控制台的「資料庫」頁面。

    前往「資料庫」

  2. 從資料庫清單中選取所需資料庫。

  3. 在導覽選單中，按一下「存留時間」。

  4. 點選「建立政策」。

  5. 輸入集合名稱和時間戳記欄位名稱。

  6. 點選「建立」。

控制台會返回「存留時間」頁面。如果作業順利啟動，頁面會在 TTL 索引表新增項目。如果失敗，頁面會顯示錯誤訊息。

gcloud

  1. 安裝並初始化 gcloud CLI CLI。

  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 索引，請按照下列步驟操作：

MongoDB API

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

db.restaurants.listIndexes()

請注意，輸出內容會同時包含存留時間索引和非存留時間索引。存留時間索引會包含 expireAfterSeconds 選項。

Google Cloud Console

  1. 前往 Google Cloud 控制台的「資料庫」頁面。

    前往「資料庫」

  2. 從資料庫清單中選取所需資料庫。

  3. 在導覽選單中，按一下「存留時間」。

控制台會列出資料庫的 TTL 索引，並顯示每個索引的狀態。

gcloud

  1. 安裝並初始化 gcloud CLI CLI。

  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 索引，請按照下列步驟操作：

MongoDB API

使用 dropIndex() 方法捨棄 TTL 索引。例如：

使用索引名稱捨棄 TTL 索引

db.restaurants.dropIndex("ts_1")

使用索引定義捨棄存留時間索引

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

請注意，使用 MongoDB API 捨棄 TTL 索引的稽核記錄會使用 google.firestore.admin.v1.FirestoreAdmin.UpdateField 方法名稱。

Google Cloud Console

  1. 前往 Google Cloud 控制台的「資料庫」頁面。

    前往「資料庫」

  2. 從資料庫清單中選取所需資料庫。

  3. 在導覽選單中，按一下「存留時間」。

  4. 在 TTL 索引表格中，找到 TTL 索引的列。在這個表格列中，按一下「刪除」 (垃圾桶) 按鈕。

  5. 按一下「刪除」確認。

控制台會返回「存留時間」頁面。成功時， Cloud Firestore 會從資料表移除 TTL 索引。

gcloud

  1. 安裝並初始化 gcloud CLI CLI。

  2. 使用 firestore fields ttls update 指令設定 TTL 索引。加上 --async 旗標，避免 gcloud CLI 等待作業完成。

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

監控存留時間刪除作業

您可以使用 Cloud Monitoring 查看 TTL 驅動刪除作業的相關指標。 Cloud Firestore 提供下列 TTL 指標：

指標類型 指標名稱 指標說明
firestore.googleapis.com/document/ttl_deletion_count 存留時間刪除計數

TTL 索引刪除的文件總數。
firestore.googleapis.com/document/ttl_expiration_to_deletion_delays 從存留時間到刪除延遲

文件在 TTL 索引下過期到實際刪除之間經過的時間。

如要設定含有 Cloud Firestore 指標的資訊主頁，請參閱「管理自訂資訊主頁」和「新增資訊主頁小工具」。