TTL インデックスでデータ保持を管理する

TTL インデックスでデータ保持を管理する

このページでは、MongoDB API、 Google Cloud コンソール、Google Cloud CLI を使用して、有効期間（TTL）インデックスを構成する方法について説明します。

有効期間の概要

TTL インデックスを使用して、データベースから古いデータを自動的に削除します。TTL インデックスは、特定のフィールドを、特定のコレクション内のドキュメントの有効期限として指定します。TTL を使用すると、古いデータをクリーンアップすることでストレージ費用を削減できます。 データは通常、有効期限が切れた後 24 時間以内に削除されます。

料金

TTL 削除オペレーションでは、マネージド削除ユニットが使用されます。料金については、Firestore Enterprise エディションの料金をご覧ください。

制限と制約

• コレクションごとに作成できる TTL インデックスは 1 つのみです。
• TTL インデックスは最大 500 個まで指定できます。

TTL の削除

TTL による削除の、次の主な動作に注意してください。

• TTL による削除は短時間のプロセスではありません。TTL プロセスにより実際に削除されるまで、期限切れのドキュメントはクエリとルックアップ リクエストに引き続き表示されます。TTL では、削除の総所有コストを削減できるというメリットは、削除の適時性との引き換えとなります。データは通常、有効期限が切れた後 24 時間以内に削除されます。

• 既存のコレクションに TTL インデックスを作成すると、新しい TTL インデックスに従って期限切れとなったすべてのデータが一括削除されます。この一括削除も即時には行われず、該当するコレクションのデータの残量によって決まります。

• ドキュメントに以前の有効期限がある場合に、新しい TTL インデックスをコレクションに追加すると、TTL インデックスの設定が終了してアクティブになってから 24 時間以内にドキュメントが削除されます。

• TTL では、有効期限のタイムスタンプと同じ順序でドキュメントが削除されるとは限りません。

• 削除はトランザクション的に行われるわけではありません。有効期限が同じドキュメントが同時に削除されるとは限りません。この動作が必要な場合は、クライアント ライブラリを使用して削除を行います。

• MongoDB 互換の Firestore は、常に最新の TTL フィールドを使用して有効期限を決定します。たとえば、有効期限が切れている未削除のドキュメントの TTL フィールドを将来の日付に更新すると、そのドキュメントは期限切れにはならず、新しい日付が使用されます。

• MongoDB 互換の Firestore では、TTL フィールドが Date and time/BSON Date 値または Date and time/BSON Date 値を含む Array 値に設定されている場合にのみ、ドキュメントが期限切れになります。このフィールドを未設定のままにするか、null などの値に設定すると、ドキュメントごとに有効期限を無効にできます。

• TTL は他のデータベース アクティビティへの影響を最小限にするように設計されています。TTL による削除は、それよりも低い優先度で処理されます。また、TTL による削除が原因のトラフィックの急増を抑制するための戦略も実施されています。

TTL インデックスとの違い

他の Firestore インデックスとは異なり、TTL インデックスはクエリ プランニングでパフォーマンスを向上させるために使用されません。TTL で使用されるフィールドのクエリ パフォーマンスを向上させるには、TTL 以外の別のインデックスに追加する必要があります。

TTL フィールドはタイムスタンプを使用するため、TTL 以外のインデックスに追加するとホットスポットが発生する可能性があります。ホットスポットは、狭い範囲のドキュメント内で書き込みと削除の頻度が高くなると発生します。これにより、書き込みトラフィックが多い期間にスケーリング パフォーマンスに悪影響が及ぶ可能性があります。

権限

TTL インデックスを作成または削除するプリンシパルには、プロジェクトで次の権限が必要になります。

• TTL インデックスを表示するには、datastore.indexes.list 権限と datastore.indexes.get 権限が必要です。
• TTL インデックスを作成または削除するには、datastore.indexes.update 権限が必要です。
• TTL オペレーションのステータスを確認するには、datastore.operations.list と datastore.operations.get が必要です。

これらの権限を割り当てるロールについては、Firestore の Identity and Access Management のロールをご覧ください。

TTL インデックスを作成する

TTL インデックスを作成するときは、コレクション内のドキュメントの有効期限としてドキュメント フィールドを指定します。

TTL では、指定したフィールドを使用して削除対象のドキュメントが識別されます。TTL フィールドは、Timestamp/BSON Date 値または Timestamp/BSON Date 値を含む Array 値に設定する必要があります。すでに存在するフィールドを選択することも、後で追加するフィールドを指定することもできます。

注: 2026 年 2 月より前に作成された一部の TTL インデックスは、Array 値内の Timestamp/BSON Date 値には適用されません。Array 値に適用する TTL インデックスを更新するには、インデックスを削除して再作成します。

TTL フィールドの値を設定する前に、次の点を考慮してください。

• TTL フィールドの値は、将来、現在、過去の時刻のいずれかにできます。値が過去の時刻であれば、ドキュメントはすぐに削除できます。たとえば、expireAt フィールドで TTL インデックスを作成し、それを既存のドキュメントに追加します。

• 他のデータタイプを使用したり、TTL フィールド値を設定しなかったりすると、個々のドキュメントの TTL が無効になります。

TTL インデックスを作成する手順は次のとおりです。

MongoDB API

createIndex() メソッドを呼び出すときに expireAfterSeconds インデックス オプションを含めます。

db.COLLECTION_NAME.createIndex({"TTL_FIELD": 1, "expireAfterSeconds": EXPIRATION_OFFSET_SECONDS})

次に例を示します。

db.restaurants.createIndex({"ts": 1, "expireAfterSeconds": 3600})

expireAfterSeconds は TTL を TTL インデックスとして識別するもので、TTL フィールドのタイムスタンプ値と有効期限の間のオフセットになります。expireAfterSeconds が 0 に設定されている場合、有効期限は TTL フィールドのタイムスタンプ値から直接取得されます。

次の制約があります。

• TTL インデックスには、フィールドを 1 つだけ含める必要があります。
• TTL インデックスはクエリ プランニングでは使用されず、クエリのパフォーマンスを向上させることはありません。
• コレクションごとに作成できる TTL インデックスは 1 つのみです。
• MongoDB API を使用した TTL インデックス作成の監査ログでは、メソッド名 google.firestore.admin.v1.FirestoreAdmin.UpdateField が使用されます。

Google Cloud Console

1. Google Cloud コンソールで、[データベース] ページに移動します。

   [データベース] に移動

2. データベースのリストから、必要なデータベースを選択します。

3. ナビゲーション メニューで [有効期間（TTL）] をクリックします。

4. [Create Policy] をクリックします。

5. コレクション名とタイムスタンプ フィールド名を入力します。

6. 省略可: 有効期限のオフセットを構成します。値を入力し、単位（日、時間、分、秒）を選択します。デフォルトでは、オフセットは 0 です。

7. [作成] をクリックします。

コンソールの [有効期間（TTL）] ページに戻ります。オペレーションが正常に開始されると、TTL インデックス テーブルのページにエントリが追加されます。失敗すると、ページにエラー メッセージが表示されます。

gcloud

1. Google Cloud コンソールで Cloud Shell をアクティブにします。

   Cloud Shell をアクティブにする

   Google Cloud コンソールの下部にある Cloud Shell セッションが開始し、コマンドライン プロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。

2. firestore fields ttls update コマンドを使用して、TTL インデックスを構成します。--async フラグを追加すると、gcloud CLI はオペレーションの完了を待機しません。

    gcloud firestore fields ttls update \
     ttl_field \
     --collection-group=collection_name \
     --enable-ttl 

   有効期限オフセットを使用して TTL インデックスを有効にするには、--expiration-offset フラグを追加します。

    gcloud firestore fields ttls update \
     ttl_field \
     --collection-group=collection_name \
     --enable-ttl \
     --expiration-offset=expiration_offset 

   expiration_offset は、期間（7 日間の場合は 7d、24 時間の場合は 24h など）に置き換えます。このフラグを省略すると、有効期限オフセットはデフォルトで 0 になります。

TTL インデックスの作成時間

TTL インデックスの作成には、少なくとも 10 分以上かかることがあります。オペレーションを開始すると、ターミナルを閉じてもオペレーションはキャンセルされません。

TTL インデックスを表示する

TTL インデックスを表示する手順は次のとおりです。

MongoDB API

listIndexes() メソッドを使用して、TTL インデックスを表示します。次に例を示します。

db.restaurants.listIndexes()

出力には、TTL インデックスと TTL 以外のインデックスの両方が含まれます。TTL インデックスには expireAfterSeconds オプションが含まれます。

Google Cloud Console

1. Google Cloud コンソールで、[データベース] ページに移動します。

   [データベース] に移動

2. データベースのリストから、必要なデータベースを選択します。

3. ナビゲーション メニューで [有効期間（TTL）] をクリックします。

コンソールには、データベースの TTL インデックスが表示され、各インデックスのステータスも含まれます。

gcloud

1. Google Cloud コンソールで Cloud Shell をアクティブにします。

   Cloud Shell をアクティブにする

   Google Cloud コンソールの下部にある Cloud Shell セッションが開始し、コマンドライン プロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。

2. firestore fields ttls list コマンドを使用して、TTL インデックスを構成します。次のコマンドを実行すると、すべての TTL インデックスが一覧表示されます。

   gcloud firestore fields ttls list
   

   特定のコレクションの TTL インデックスを一覧表示するには、次のコマンドを使用します。

   gcloud firestore fields ttls list  --collection-group=collection_name
   

オペレーションの詳細の表示

ステータスが CREATING の TTL インデックスの詳細は、gcloud CLI を使用して確認できます。

operations list コマンドを使用して、実行中のオペレーションと最近完了したすべてのオペレーションを表示します。

gcloud firestore operations list

レスポンスには、オペレーションの推定の進捗状況が含まれます。

TTL インデックスを削除する

TTL インデックスを削除する手順は次のとおりです。

MongoDB API

dropIndex() メソッドを使用して、TTL インデックスを削除します。次に例を示します。

インデックス名を使用して TTL インデックスを削除する

db.restaurants.dropIndex("ts_1")

インデックス定義を使用して TTL インデックスを削除する

db.restaurants.dropIndex({"ts": 1})

MongoDB API を使用して TTL インデックスを削除する監査ログでは、メソッド名 google.firestore.admin.v1.FirestoreAdmin.UpdateField が使用されます。

注: MongoDB の drop() コマンドを使用してコレクションを削除すると、そのコレクションに構成されている TTL インデックスが自動的に削除されます。ドロップ コレクションはプレビュー版です。

Google Cloud Console

1. Google Cloud コンソールで、[データベース] ページに移動します。

   [データベース] に移動

2. データベースのリストから、必要なデータベースを選択します。

3. ナビゲーション メニューで [有効期間（TTL）] をクリックします。

4. TTL インデックス テーブルで、TTL インデックスの行を見つけます。このテーブル行で、削除（ゴミ箱）ボタンをクリックします。

5. [削除] をクリックして確定します。

コンソールの [有効期間（TTL）] ページに戻ります。成功すると、MongoDB 互換の Firestore はテーブルから TTL インデックスを削除します。

gcloud

1. Google Cloud コンソールで Cloud Shell をアクティブにします。

   Cloud Shell をアクティブにする

   Google Cloud コンソールの下部にある Cloud Shell セッションが開始し、コマンドライン プロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。

2. firestore fields ttls update コマンドを使用して、TTL インデックスを構成します。--async フラグを追加すると、gcloud CLI はオペレーションの完了を待機しません。

   gcloud firestore fields ttls update ttl_field --collection-group=collection_name --disable-ttl
   

TTL の削除のモニタリング

Cloud Monitoring を使用すると、TTL による削除に関する指標を表示できます。MongoDB 互換の Firestore では、TTL について次の指標を提供しています。

指標タイプ	指標名	指標の説明
firestore.googleapis.com/document/ttl_deletion_count	有効期間による削除数	TTL インデックスによって削除されたドキュメントの合計数。
firestore.googleapis.com/document/ttl_expiration_to_deletion_delays	有効期間の期限切れから削除までの遅延	TTL インデックスに基づいてドキュメントが期限切れになってから実際に削除されるまでの経過時間。

MongoDB 互換の Firestore の指標を使用してダッシュボードを設定するには、カスタム ダッシュボードを管理するとダッシュボード ウィジェットを追加するをご覧ください。