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

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

存留時間總覽

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

定價

TTL 刪除作業會使用代管刪除單位。如要瞭解定價，請參閱「Cloud Firestore Enterprise 版定價」。

限制和約束

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

依據存留時間刪除

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

  • 透過 TTL 刪除資料並非即時程序。在 TTL 程序實際刪除過期文件之前，這些文件仍會顯示在查詢和查詢要求中。TTL 雖然會延遲刪除作業，但能降低刪除作業的總持有成本。通常會在到期時間後的 24 小時內刪除資料。

  • 在現有集合上建立存留時間索引，會導致系統根據新的存留時間索引大量刪除所有過期資料。請注意，這項大量刪除作業也不是即時完成，而是取決於該集合中的資料量。

  • 如果文件的到期時間已過，而您在集合中新增了存留時間索引，系統會在存留時間索引設定完成並生效後的 24 小時內刪除該文件。

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

  • 刪除作業不會以交易方式執行。到期時間相同的文件不一定會同時刪除。如需這項行為，請使用用戶端程式庫執行刪除作業。

  • Cloud Firestore 一律會依據最新的存留時間欄位決定到期時間。舉例來說，如果已過期但尚未刪除的文件，其存留時間欄位更新為較晚的日期，則該文件不會過期，並會使用新的日期。

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

  • TTL 的設計旨在盡可能減少對其他資料庫活動的影響。由存留時間驅動的刪除作業優先順序較低。我們也採取其他策略，緩解 TTL 驅動刪除作業造成的流量高峰。

與 TTL 索引的差異

與其他 Firestore 索引不同，TTL 索引不會在查詢規劃期間用於提升效能。如要提升與 TTL 搭配使用的欄位查詢效能，請務必將該欄位新增至獨立的非 TTL 索引。

請注意，由於存留時間欄位使用時間戳記，將其新增至非存留時間索引可能會導致熱點。如果寫入和刪除作業大量集中在少數文件中，就會產生熱點，在寫入流量龐大時，可能會對擴充效能造成負面影響。

權限

建立或捨棄存留時間索引的主體，必須具備專案中的下列權限：

  • 如要查看存留時間索引，必須具備 datastore.indexes.list 和 datastore.indexes.get 權限。
  • 必須具備 datastore.indexes.update 權限，才能建立或捨棄存留時間索引。
  • 如要查看存留時間作業的狀態，必須具備 datastore.operations.list 和 datastore.operations.get。

如要瞭解哪些角色會指派這些權限，請參閱「Cloud Firestore Identity and Access Management 角色」。

建立 TTL 索引

建立存留時間索引時，您需要指定一個文件欄位，做為集合中文件的到期時間。

TTL 會使用指定欄位來識別可刪除的文件。TTL 欄位必須設為 Timestamp/BSON Date 值，或包含 Timestamp/BSON Date 值的 Array 值。您可以選取現有欄位，也可以指定稍後要新增的欄位。

設定存留時間欄位值前，請考量下列事項：

  • TTL 欄位值可以是未來、現在或過去的時間。如果值是過去的時間，文件就會立即符合刪除資格。舉例來說，您可以建立含有 expireAt 欄位的存留時間索引，然後將該索引新增至現有文件。

  • 如果使用任何其他資料類型，或未設定存留時間欄位值，系統會停用個別文件的存留時間。

如要建立存留時間索引，請按照下列步驟操作：

MongoDB API

呼叫 createIndex() 方法時，請加入 expireAfterSeconds 索引選項：

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

例如：

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

expireAfterSeconds 會將存留時間識別為存留時間索引，並代表存留時間欄位中的時間戳記值與到期時間之間的偏移量。如果 expireAfterSeconds 設為 0，到期時間會直接由 TTL 欄位中的時間戳記值提供。

請注意下列限制：

  • 存留時間索引只能包含一個欄位。
  • TTL 索引不會用於查詢計畫，也不會提高查詢效能。
  • 每個集合只能建立一個存留時間索引。
  • 使用 MongoDB API 建立 TTL 索引的稽核記錄會使用方法名稱 google.firestore.admin.v1.FirestoreAdmin.UpdateField。

Google Cloud Console

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

    前往「資料庫」

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

  3. 在導覽選單中，按一下「Time-to-live」(存留時間)。

  4. 點按「建立政策」。

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

  6. 選用：設定「Expiration offset」(到期偏移)。輸入值並選取單位 (天、小時、分鐘或秒)。預設值為 0。

  7. 點選「建立」。

控制台會返回「Time-to-live」(存留時間) 頁面。如果作業成功啟動，頁面會在 TTL 索引資料表中新增項目。如果失敗，頁面會顯示錯誤訊息。

gcloud

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

  2. 使用 firestore fields ttls update 指令設定存留時間索引。新增 --async 旗標，防止 gcloud CLI 等待作業完成。

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

    如要啟用具有到期偏移量的 TTL 索引，請新增 --expiration-offset 旗標：

     gcloud firestore fields ttls update \
  ttl_field \
  --collection-group=collection_name \
  --enable-ttl \
  --expiration-offset=expiration_offset

    將 expiration_offset 替換為時間長度，例如 7d 代表 7 天，24h 代表 24 小時。如果省略這個旗標，到期偏移量預設為 0。

TTL 索引建立時間

建立存留時間索引至少需要十分鐘。作業啟動後，關閉終端機並不會取消作業。

查看 TTL 索引

如要查看 TTL 索引，請按照下列步驟操作：

MongoDB API

使用 listIndexes() 方法查看存留時間索引。例如：

db.restaurants.listIndexes()

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

Google Cloud Console

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

    前往「資料庫」

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

  3. 在導覽選單中，按一下「Time-to-live」(存留時間)。

控制台會列出資料庫的存留時間索引，並顯示各索引的狀態。

gcloud

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

  2. 使用 firestore fields ttls list 指令設定存留時間索引。下列指令會列出所有 TTL 索引。

    gcloud firestore fields ttls list

    如要列出特定集合下的存留時間索引，請使用下列指令：

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

查看作業詳細資料

您可以使用 gcloud CLI 查看處於 CREATING 狀態的 TTL 索引詳細資料。

使用 operations list 指令，查看所有執行中和最近完成的作業：

gcloud firestore operations list

回應會包含作業進度的預估值。

捨棄存留時間索引

如要捨棄存留時間索引，請按照下列步驟操作：

MongoDB API

使用 dropIndex() 方法捨棄存留時間索引。例如：

使用索引名稱捨棄存留時間索引

db.restaurants.dropIndex("ts_1")

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

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

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

Google Cloud Console

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

    前往「資料庫」

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

  3. 在導覽選單中，按一下「Time-to-live」(存留時間)。

  4. 在存留時間索引表中，找到存留時間索引所在的資料列。在該表格列中，按一下「Delete」(刪除) (垃圾桶) 按鈕。

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

控制台會返回「Time-to-live」(存留時間) 頁面。成功後，Cloud Firestore 會從資料表中移除存留時間索引。

gcloud

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

  2. 使用 firestore fields ttls update 指令設定存留時間索引。新增 --async 旗標，防止 gcloud CLI 等待作業完成。

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

監控存留時間刪除作業

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

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

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

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

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