Azure Cosmos DB の Time to Live (TTL)

  • [アーティクル]

適用対象: NoSQL

Time to Live (TTL) を使用すると、Azure Cosmos DB に、所定の期間が経過したアイテムをコンテナーから自動的に削除させることができます。 既定では、コンテナー レベルで Time to Live を設定し、項目ごとに値をオーバーライドできます。 コンテナー レベルまたは項目レベルで TTL を設定すると、項目が最後に変更されてからその期間が経過した後で、Azure Cosmos DB によってそれらの項目が自動的に削除されます。 Time to Live 値は秒数で構成します。 TTL を構成すると、その TTL 値に基づき、期限切れになったアイテムが自動的に削除されます。クライアント アプリケーションから明示的に削除操作を発行する必要はありません。 TTL の最大値は 2,147,483,647 秒で、24,855 日または 68 年に相当します。

期限切れアイテムの削除は、まだユーザー要求で消費されていない残りの要求ユニットを使用し、バックグラウンド タスクとして実行されます。 コンテナーが多量の要求で過負荷になり、十分な RU を使用できない場合は、TTL の期限が切れていてもデータ削除は延期されます。 削除操作を実行するのに十分な RU が利用可能になると、データは削除されます。 ただし、データ削除が延期されている場合も、TTL の期限が切れたデータは、クエリに対して返されることはありません (どの API によるクエリであっても)。

Note

このコンテンツは Azure Cosmos DB トランザクション ストア TTL に関連付けられています。 Azure Synapse Link 経由で NoETL HTAP シナリオを可能にする分析ストア TTL をお探しの場合、こちらをクリックしてください。

コンテナーおよび項目の Time to Live

TTL 値は秒数で設定され、アイテムに最後に変更が加えられた日時からの経過時間として解釈されます。 コンテナーまたはコンテナー内の項目に対して Time to Live を設定できます。

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

    • 未設定の場合 (または設定値が null の場合)、アイテムが自動的に期限切れになることはありません。

    • 設定が存在する場合、値が "-1" であれば "無限" を意味し、既定でアイテムの期限切れは発生しません。

    • 設定が存在する場合、値がゼロ以外の数値 (n) であれば、最終変更日時から n 秒が経過したアイテムは期限切れになります。

  2. 項目の Time to Live (ttl を使用):

    • このプロパティは、親コンテナーに対して DefaultTimeToLive が存在し、その設定値が null 以外である場合にのみ適用されます。

    • 存在する場合、これが親コンテナーの DefaultTimeToLive 値をオーバーライドします。

Time to Live の構成

  • TTL がコンテナーで "n" に設定されている場合、そのコンテナー内の項目は n 秒後に期限切れになります。 同じコンテナー内のアイテムに独自の有効期間が設定される場合は、-1 (期限切れにしない) に設定します。 コンテナーとは異なる TTL が個別に設定されているアイテムがある場合、それらは、個別に設定された TTL 値に基づいて期限切れになります。

  • コンテナーの TTL が設定されていない場合、そのコンテナー内のアイテムに設定された TTL は効力を持ちません。

  • コンテナーの TTL が -1 に設定されている場合、そのコンテナー内にあるアイテムのうち、TTL が n に設定されているものは n 秒後に期限切れになり、その他のアイテムは期限切れになりません。

例

このセクションでは、異なる Time to Live 値がコンテナーおよびアイテムに割り当てられたいくつかの例を示します。

Note

アイテムの TTL 値を null にする設定はサポートされていません。 アイテムの TTL 値は、0 でなく 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 は有効です。 項目は、1,000 秒後に期限切れになります (既定)。
ttl = -1 TTL は有効です。 項目は無期限に設定されます。
ttl = 2000 TTL は有効です。 項目は、2000 秒後に期限切れになります。

次のステップ

Time to Live を構成する方法について次の記事をご覧ください。