本頁面說明如何使用 Google Cloud 主控台和 Google Cloud CLI 設定時間到期 (TTL) 政策。閱讀本頁面之前，請先瞭解 Cloud Firestore 資料模型。
存留時間總覽
使用 TTL 政策，自動移除資料庫中的過時資料。存留時間政策會將特定欄位指定為特定集合群組中文件的到期時間。您可以透過 TTL 清除過時的資料，降低儲存空間成本。通常會在到期日後的 24 小時內刪除資料。
定價
TTL 刪除作業會計入文件刪除費用。如要瞭解刪除作業的價格，請參閱 Cloud Firestore 定價。
限制
- 每個集合群組只能標示一個欄位為 TTL 欄位。
- 您最多可以設定 200 個欄位層級設定。一個欄位設定可包含相同欄位的多個設定。舉例來說，如果單一欄位索引豁免設定和同一個欄位的 TTL 政策都計入限制，就會造成一個欄位設定。
- 對於 Datastore 模式的 Firestore 客戶，存留時間無法與 Optimistic With Entity Groups 並行模式搭配使用。建議您將並行模式變更為樂觀並行模式。
刪除存留時間
請注意 TTL 驅動刪除作業的下列重要行為：
透過 TTL 刪除並非即時程序，過期文件會持續顯示在查詢和查閱要求中，直到 TTL 程序實際刪除這些文件為止。存留時間可讓您在刪除時程和刪除作業的總持有成本之間取得平衡。通常會在到期日後的 24 小時內刪除資料。
透過 TTL 刪除文件時，系統不會刪除該文件下的子集合。
在現有集合群組上套用存留時間政策後，系統會根據新存留時間政策大量刪除所有過期資料。請注意，這項大量刪除作業並非立即完成，實際時間取決於該收集群組的資料量。
如果文件的到期時間已過，而您在集合中新增了新的 TTL 政策，系統會在 TTL 政策完成設定並生效後的 24 小時內刪除該文件。
TTL 不一定會按照文件到期時間戳記的順序刪除文件。
刪除作業不會以交易方式執行。具有相同到期時間的文件不一定會在同一時間刪除。如果需要這種行為，請使用用戶端程式庫執行刪除作業。
Cloud Firestore 一律會使用最新的 TTL 欄位來判斷到期日。舉例來說，如果已過期但尚未刪除的文件，其 TTL 欄位更新為較晚的日期，則文件不會過期，系統會使用新日期。
TTL 的設計目的是盡量降低對其他資料庫活動的影響。系統會以較低的優先順序處理 TTL 觸發的刪除作業。我們也採用其他策略，以便平滑因 TTL 驅動刪除作業而造成的流量尖峰。
透過 TTL 刪除會呼叫所有有效的快照監聽器，並觸發 Cloud Functions Cloud Firestore 觸發條件。
存留時間欄位和索引
存留時間欄位可以建立索引，也可以不建立索引。不過，由於 TTL 欄位是時間戳記，因此為該欄位建立索引可能會影響較高流量率的效能。為時間戳記欄位建立索引可能會產生熱點，這違反最佳做法。熱點是指讀取、寫入和刪除頻率高的狹小文件範圍。
根據預設，Cloud Firestore 會為所有欄位建立單一欄位索引。您可以建立單一欄位索引豁免設定，停用 TTL 欄位的索引。
權限
設定存留時間政策的使用者必須具備專案中的下列權限：
- 您必須具備
datastore.indexes.list和datastore.indexes.get權限，才能查看 TTL 政策。 - 您必須具備
datastore.indexes.update權限，才能修改 TTL 政策。 - 您必須使用
datastore.operations.list和datastore.operations.get才能查看 TTL 作業的狀態。
如要瞭解指派這些權限的角色，請參閱 Cloud Firestore 身分與存取權管理角色。
事前準備
使用 gcloud CLI 管理 TTL 政策前，請先使用 gcloud components update 指令將元件更新至最新可用版本：
gcloud components update
建立存留時間政策
建立存留時間政策時，您可以指定文件欄位做為集合群組中文件的到期時間。
TTL 會使用指定的欄位，識別可刪除的文件。這個 TTL 欄位必須是 Date and time 類型。您可以選取現有的欄位，也可以指定日後要新增的欄位。
設定 TTL 欄位值前，請考量以下事項：
TTL 欄位值可以是未來、現在或過去的時間。如果值是過去的時間，則文件即可立即刪除。舉例來說，您可以使用
expireAt欄位建立 TTL 政策，然後新增至現有文件。使用任何其他資料類型或未設定 TTL 欄位值，都會停用個別文件的 TTL。
如要建立 TTL 政策，請按照下列步驟操作：
Google Cloud Console
前往 Google Cloud 控制台的「Databases」頁面。
從資料庫清單中選取必要資料庫。
在導覽選單中，按一下「Time-to-live」(生命週期)。
點選「建立政策」。
輸入收集群組名稱和時間戳記欄位名稱。
按一下「建立」。
控制台會返回「Time-to-live」頁面。如果作業順利啟動，頁面會在 TTL 政策表格中新增項目。如果失敗，頁面會顯示錯誤訊息。
gcloud
使用 firestore fields ttls
update 指令設定 TTL 政策。新增 --async 標記，避免 gcloud CLI 為了等待作業完成而停頓。
gcloud firestore fields ttls update ttl_field --collection-group=collection_group_name --enable-ttl
存留時間政策啟用期間
即使資料庫為空白，啟用 TTL 政策也可能需要十分鐘以上。啟動作業後，關閉終端機不會取消作業。
查看存留時間政策
如要查看 TTL 政策及其狀態，請按照下列步驟操作：
Google Cloud Console
前往 Google Cloud 控制台的「Databases」頁面。
從資料庫清單中選取必要資料庫。
在導覽選單中，按一下「Time-to-live」(生命週期)。
控制台會列出資料庫的 TTL 政策，並附上每項政策的狀態。
gcloud
使用 firestore fields ttls list 指令設定 TTL 政策。下列指令會列出所有 TTL 政策。
gcloud firestore fields ttls list
如要列出特定集合群組下的 TTL 政策，請使用以下指令：
gcloud firestore fields ttls list --collection-group=collection_group_name
查看作業詳細資料
您可以使用 gcloud CLI 查看 TTL 政策的更多詳細資料，瞭解其處於 CREATING 狀態。
使用 operations list 指令查看所有執行中和最近完成的作業：
gcloud firestore operations list
回應中會包含作業進度的預估值。
停用存留時間政策
如要停用 TTL 政策，請按照下列步驟操作：
Google Cloud Console
前往 Google Cloud 控制台的「Databases」頁面。
從資料庫清單中選取必要資料庫。
在導覽選單中，按一下「Time-to-live」(生命週期)。
在存留時間政策表格中，找出存留時間政策的資料列。在這個資料表列中，按一下「刪除」 (垃圾桶) 按鈕。
按一下「刪除」確認。
控制台會返回「Time-to-live」頁面。如果成功，Cloud Firestore 會從表格中移除 TTL 政策。
gcloud
1. 使用 firestore fields ttls update 指令設定 TTL 政策。新增 --async 標記，避免 gcloud CLI 為了等待作業完成而停頓。
gcloud firestore fields ttls update ttl_field --collection-group=collection_group_name --disable-ttl
監控存留時間刪除作業
您可以使用 Cloud Monitoring 查看 TTL 驅動刪除作業的指標。Cloud Firestore 提供下列 TTL 指標：
| 指標類型 | 指標名稱 | 指標說明 |
|---|---|---|
| firestore.googleapis.com/document/ttl_deletion_count | 存留時間刪除計數 |
存留時間政策刪除的文件總數。 |
| firestore.googleapis.com/document/ttl_expiration_to_deletion_delays | 存留時間到期到刪除的延遲時間 |
文件在 TTL 政策到期後，實際刪除前所經過的時間。 |
如要設定含有 Cloud Firestore 指標的資訊主頁，請參閱「管理自訂資訊主頁」和「新增資訊主頁小工具」。