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