Azure Cosmos DB の Time to Live (TTL)Time to Live (TTL) in Azure Cosmos DB

適用対象: SQL API

Azure Cosmos DB は、Time to Live (TTL) を使用して、一定の期間が経過したらアイテムをコンテナーから自動的に削除する機能を提供します。With Time to Live or TTL, Azure Cosmos DB provides the ability to delete items automatically from a container after a certain time period. 既定では、コンテナー レベルで Time to Live を設定し、項目ごとに値をオーバーライドできます。By default, you can set time to live at the container level and override the value on a per-item basis. コンテナー レベルまたは項目レベルで TTL を設定すると、項目が最後に変更されてからその期間が経過した後で、Azure Cosmos DB によってそれらの項目が自動的に削除されます。After you set the TTL at a container or at an item level, Azure Cosmos DB will automatically remove these items after the time period, since the time they were last modified. Time to Live 値は秒数で構成します。Time to live value is configured in seconds. TTL を構成すると、TTL 値に基づいてシステムが自動的に期限切れアイテムを削除します。クライアント アプリケーションが明示的に発行する削除操作は必要ありません。When you configure TTL, the system will automatically delete the expired items based on the TTL value, without needing a delete operation that is explicitly issued by the client application. TTL の最大値は 2147483647 です。The maximum value for TTL is 2147483647.

期限切れアイテムの削除は、残っている要求ユニット、つまりユーザー要求によってまだ消費されていない要求ユニットを消費するバックグラウンド タスクです。Deletion of expired items is a background task that consumes left-over Request Units, that is Request Units that haven't been consumed by user requests. TTL の期限が切れた後であっても、要求のためにコンテナーが過負荷の状態で、使用できる RU が十分にない場合、データの削除は遅延します。Even after the TTL has expired, if the container is overloaded with requests and if there aren't enough RU's available, the data deletion is delayed. 削除操作を実行するのに十分な RU が利用可能になると、データは削除されます。Data is deleted once there are enough RUs available to perform the delete operation. たとえデータの削除が遅延しても、TTL の期限が切れた後は、どんなクエリによっても (どんな API によっても) データが返されることはありません。Though the data deletion is delayed, data is not returned by any queries (by any API) after the TTL has expired.

このコンテンツは Azure Cosmos DB トランザクション ストア TTL に関連付けられています。This content is related to Azure Cosmos DB transactional store TTL. Azure Synapse Link 経由で NoETL HTAP シナリオを可能にする分析ストア TTL をお探しの場合、こちらをクリックしてください。If you are looking for analytical store TTL, that enables NoETL HTAP scenarios through Azure Synapse Link, please click here.

コンテナーおよび項目の Time to LiveTime to live for containers and items

Time to Live 値は秒数で設定され、項目が最後に変更された時間との差分として解釈されます。The time to live value is set in seconds, and it is interpreted as a delta from the time that an item was last modified. コンテナーまたはコンテナー内の項目に対して Time to Live を設定できます。You can set time to live on a container or an item within the container:

  1. コンテナーの Time to Live (DefaultTimeToLive を使用して設定):Time to Live on a container (set using DefaultTimeToLive):

    • 設定されていない (または null に設定されている) 場合、項目の期限が自動的に切れることはありません。If missing (or set to null), items are not expired automatically.

    • 値が存在し "-1" (無限) に設定されている場合、既定で項目は期限切れになりません。If present and the value is set to "-1", it is equal to infinity, and items don’t expire by default.

    • 値が存在し、値が "ゼロ以外の" いずれかの数 ( "n" ) に設定されている場合、項目は最終変更時刻から "n" 秒後に期限切れになります。If present and the value is set to some non-zero number "n" – items will expire "n" seconds after their last modified time.

  2. 項目の Time to Live (ttl を使用):Time to Live on an item (set using ttl):

    • このプロパティを適用できるのは、DefaultTimeToLive が存在し、親コンテナーに対して null に設定されていない場合のみです。This Property is applicable only if DefaultTimeToLive is present and it is not set to null for the parent container.

    • 存在する場合、これが親コンテナーの DefaultTimeToLive 値をオーバーライドします。If present, it overrides the DefaultTimeToLive value of the parent container.

Time to Live の構成Time to Live configurations

  • TTL がコンテナーで "n" に設定されている場合、そのコンテナー内の項目は n 秒後に期限切れになります。If TTL is set to "n" on a container, then the items in that container will expire after n seconds. 同じコンテナー内に独自の Time to Live が -1 (期限切れしないことを示す) に設定されている項目がある場合、または一部の項目の Time to Live 設定が異なる数値でオーバーライドされた場合、これらの項目はそれぞれに構成されている TTL 値に基づいて期限切れになります。If there are items in the same container that have their own time to live, set to -1 (indicating they do not expire) or if some items have overridden the time to live setting with a different number, these items expire based on their own configured TTL value.

  • TTL がコンテナーに設定されていない場合、そのコンテナー内の項目の Time to Live は無効になります。If TTL is not set on a container, then the time to live on an item in this container has no effect.

  • コンテナーの TTL が -1 に設定されている場合、そのコンテナー内にある Time to Live が n に設定されている項目は n 秒後に期限切れになり、その他の項目は期限切れになりません。If TTL on a container is set to -1, an item in this container that has the time to live set to n, will expire after n seconds, and remaining items will not expire.

Examples

このセクションでは、異なる Time to Live 値がコンテナーおよびアイテムに割り当てられたいくつかの例を示します。This section shows some examples with different time to live values assigned to container and items:

例 1Example 1

コンテナーの TTL を null に設定 (DefaultTimeToLive = null)TTL on container is set to null (DefaultTimeToLive = null)

項目の TTLTTL on item 結果Result
ttl = nullttl = null TTL は無効です。TTL is disabled. 項目は無期限に設定されます (既定)。The item will never expire (default).
ttl = -1ttl = -1 TTL は無効です。TTL is disabled. 項目は無期限に設定されます。The item will never expire.
ttl = 2000ttl = 2000 TTL は無効です。TTL is disabled. 項目は無期限に設定されます。The item will never expire.

例 2Example 2

コンテナーの TTL を -1 に設定 (DefaultTimeToLive = -1)TTL on container is set to -1 (DefaultTimeToLive = -1)

項目の TTLTTL on item 結果Result
ttl = nullttl = null TTL は有効です。TTL is enabled. 項目は無期限に設定されます (既定)。The item will never expire (default).
ttl = -1ttl = -1 TTL は有効です。TTL is enabled. 項目は無期限に設定されます。The item will never expire.
ttl = 2000ttl = 2000 TTL は有効です。TTL is enabled. 項目は、2000 秒後に期限切れになります。The item will expire after 2000 seconds.

例 3Example 3

コンテナーの TTL を 1000 に設定 (DefaultTimeToLive = 1000)TTL on container is set to 1000 (DefaultTimeToLive = 1000)

項目の TTLTTL on item 結果Result
ttl = nullttl = null TTL は有効です。TTL is enabled. 項目は、1,000 秒後に期限切れになります (既定)。The item will expire after 1000 seconds (default).
ttl = -1ttl = -1 TTL は有効です。TTL is enabled. 項目は無期限に設定されます。The item will never expire.
ttl = 2000ttl = 2000 TTL は有効です。TTL is enabled. 項目は、2000 秒後に期限切れになります。The item will expire after 2000 seconds.

次のステップNext steps

Time to Live を構成する方法について次の記事をご覧ください。Learn how to configure Time to Live in the following articles: