Azure Cosmos DB 中的存留時間 (TTL)

  • 發行項

適用於：NoSQL

使用「存留時間」或 TTL 時，Azure Cosmos DB 會在一段時間後自動從容器中刪除項目。 根據預設，您可以在容器層級設定存留時間，且覆寫每個項目的值。 在容器或項目層級設定 TTL 之後，Azure Cosmos DB 會在自從上次修改以來的時間週期後自動移除這些項目。 存留時間值會以秒設定。 當您設定 TTL 時，系統會根據 TTL 值來自動刪除過期項目，而不需要用戶端應用程式所明確發出的刪除作業。 TTL 的最大值為 2147483647 秒，大約相當於 24,855 天或 68 年。

刪除過期項目是背景工作，而此工作會取用使用者要求未取用的剩下要求單位。 甚至在 TTL 到期之後，如果容器因要求而多載，而且沒有足夠的可用 RU，則會延遲資料刪除。 一旦有足夠的 RU 可用來執行刪除作業後，就會刪除資料。 雖然資料刪除延遲，但在 TTL 到期之後，任何查詢 (透過任何 API) 都不會傳回資料。

注意

此內容與 Azure Cosmos DB 的交易式存放區 TTL 相關。 如果您要尋找可透過 Azure Synapse Link 啟用 NoETL HTAP 案例的分析存放區 TTL，請按一下這裡。

容器和項目的存留時間

存留時間值會以秒設定，而且會解譯為自項目上次修改以來的時間差異。 您可以設定容器或容器內項目的存留時間：

  1. 容器的存留時間 (使用 DefaultTimeToLive 設定)：

    • 如果遺漏 (或設定為 null)，則項目不會自動過期。

    • 如果啟用此功能並將值設為 "-1"，則存留時間等於無限，項目預設為不會到期。

    • 如果啟用此功能並將值設為某個「非零」數字："n"，則項目會在前次修改時間後的 "n" 秒到期。

  2. 項目的存留時間 (使用 ttl 設定)：

    • 只有在父容器啟用 DefaultTimeToLive 且未設定為 null 時，此屬性才適用。

    • 如果有的話，它會覆寫父容器的 DefaultTimeToLive 值。

存留時間組態

  • 如果容器的 TTL 設定為 "n"，則該容器中的項目將會在 n 秒後過期。 如果相同容器中有項目具有自己的存留時間，則請設定為 -1 (指出其不會過期)。 如果一些項目將存留時間設定覆寫為不同的數字，則這些項目會根據自己設定的 TTL 值而過期。

  • 如果未設定容器的 TTL，則此容器中項目的存留時間沒有任何作用。

  • 如果容器的 TTL 設定為 -1，則此容器中存留時間設為 n 的項目會在 n 秒後過期，而其餘的項目則不會過期。

範例

本節說明指派給容器和項目的一些不同存留時間值範例：

注意

不支援將項目上的 TTL 設定為 null。 項目 TTL 值必須是小於或等於 2147483647 的非零正整數，或 -1，這表示項目將永遠不會過期。 若要在項目上使用預設 TTL，請確定 TTL 屬性不存在。

範例 1

容器上的 TTL 設為 null (DefaultTimeToLive = null)

項目上的 TTL 結果
遺漏 ttl 屬性 TTL 已停用。 項目將永遠不會過期 (預設)。
ttl = -1 TTL 已停用。 項目永遠不會過期。
ttl = 2000 TTL 已停用。 項目永遠不會過期。

範例 2

容器上的 TTL 設定為 -1 (DefaultTimeToLive = -1)

項目上的 TTL 結果
遺漏 ttl 屬性 已啟用 TTL。 項目將永遠不會過期 (預設)。
ttl = -1 已啟用 TTL。 項目永遠不會過期。
ttl = 2000 已啟用 TTL。 項目將在 2000 秒後過期。

範例 3

容器上的 TTL 設定為 1000 (DefaultTimeToLive = 1000)

項目上的 TTL 結果
遺漏 ttl 屬性 已啟用 TTL。 項目會在 1000 秒之後過期 (預設)。
ttl = -1 已啟用 TTL。 項目永遠不會過期。
ttl = 2000 已啟用 TTL。 項目將在 2000 秒後過期。

下一步

在下列文章中了解如何設定存留時間：