このページでは、MongoDB API、Google Cloud コンソール、Google Cloud CLI を使用して、有効期間（TTL）インデックスを構成する方法について説明します。
有効期間の概要
TTL インデックスを使用して、データベースから古いデータを自動的に削除します。TTL インデックスは、特定のフィールドを、特定のコレクション内のドキュメントの有効期限として指定します。TTL を使用すると、古いデータをクリーンアップすることでストレージ費用を削減できます。 データは通常、有効期限が切れた後 24 時間以内に削除されます。
料金
TTL の削除オペレーションは、ドキュメントの削除費用にカウントされます。削除オペレーションの料金については、Cloud Firestore Enterprise エディションの料金をご覧ください。
制限と制約
- コレクションごとに作成できる TTL インデックスは 1 つのみです。
- TTL インデックスは最大 500 個まで指定できます。
TTL の削除
TTL による削除の、次の主な動作に注意してください。
TTL による削除は短時間のプロセスではありません。TTL プロセスにより実際に削除されるまで、期限切れのドキュメントはクエリとルックアップ リクエストに引き続き表示されます。TTL では、削除の総所有コストを削減できるというメリットは、削除の適時性との引き換えとなります。データは通常、有効期限が切れた後 24 時間以内に削除されます。
既存のコレクションに TTL インデックスを作成すると、新しい TTL インデックスに従って期限切れとなったすべてのデータが一括削除されます。この一括削除も即時には行われず、該当するコレクションのデータの残量によって決まります。
ドキュメントに以前の有効期限がある場合に、新しい TTL インデックスをコレクションに追加すると、TTL インデックスの設定が終了してアクティブになってから 24 時間以内にドキュメントが削除されます。
TTL では、有効期限のタイムスタンプと同じ順序でドキュメントが削除されるとは限りません。
削除はトランザクション的に行われるわけではありません。有効期限が同じドキュメントが同時に削除されるとは限りません。この動作が必要な場合は、クライアント ライブラリを使用して削除を行います。
Cloud Firestore は、常に最新の TTL フィールドを使用して有効期限を決定します。たとえば、有効期限が切れている未削除のドキュメントの TTL フィールドを将来の日付に更新すると、そのドキュメントは期限切れにはならず、新しい日付が使用されます。
Cloud Firestore では、TTL フィールドが
Date and time/BSON Date値またはDate and time/BSON Date値を含むArray値に設定されている場合にのみ、ドキュメントが期限切れになります。このフィールドを未設定のままにするか、nullなどの値に設定すると、ドキュメントごとに有効期限を無効にできます。TTL は他のデータベース アクティビティへの影響を最小限にするように設計されています。TTL による削除は、それよりも低い優先度で処理されます。また、TTL による削除が原因のトラフィックの急増を抑制するための戦略も実施されています。
TTL フィールドと TTL 以外のインデックス
TTL フィールドは、インデックス付きにすることも、インデックスなしにすることもできます。ただし、TTL フィールドはタイムスタンプであるため、TTL 以外のインデックスにこのフィールドを含めると、トラフィック レートが高い場合にパフォーマンスに影響することがあります。TTL 以外のインデックスにタイムスタンプ フィールドを含めると、ホットスポットが発生する可能性があり、これはベスト プラクティスに反します。ホットスポットは、狭いドキュメント範囲に対する高頻度の読み取り、書き込み、削除を指します。
権限
TTL インデックスを作成または削除するプリンシパルには、プロジェクトで次の権限が必要です。
- TTL インデックスを表示するには、
datastore.indexes.list権限とdatastore.indexes.get権限が必要です。 - TTL インデックスの作成または削除には、
datastore.indexes.update権限が必要です。 - TTL オペレーションのステータスを確認するには、
datastore.operations.listとdatastore.operations.getが必要です。
これらの権限を割り当てるロールについては、Cloud Firestore の Identity and Access Management ロールをご覧ください。
始める前に
gcloud CLI を使用して TTL インデックスを管理する前に、gcloud components update コマンドを使用して、コンポーネントを利用可能な最新バージョンに更新します。
gcloud components update
TTL インデックスを作成する
TTL インデックスを作成するときは、コレクション内のドキュメントの有効期限としてドキュメント フィールドを指定します。
TTL では、指定したフィールドを使用して削除対象のドキュメントが識別されます。TTL フィールドは、Timestamp/BSON Date 値または Timestamp/BSON Date 値を含む Array 値に設定する必要があります。すでに存在するフィールドを選択することも、後で追加するフィールドを指定することもできます。
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
Google Cloud コンソールで [データベース] ページに移動します。
データベースのリストから、必要なデータベースを選択します。
ナビゲーション メニューで [有効期間（TTL）] をクリックします。
[Create Policy] をクリックします。
コレクション名とタイムスタンプ フィールド名を入力します。
[作成] をクリックします。
コンソールの [有効期間（TTL）] ページに戻ります。オペレーションが正常に開始されると、TTL インデックス テーブルのページにエントリが追加されます。失敗すると、ページにエラー メッセージが表示されます。
gcloud
firestore fields ttls updateコマンドを使用して、TTL インデックスを構成します。--asyncフラグを追加すると、gcloud CLI ツールはオペレーションの完了を待機しません。gcloud firestore fields ttls update ttl_field --collection-group=collection_name --enable-ttl
TTL インデックスの作成時間
空のデータベースであっても、TTL インデックスの作成に 10 分以上かかることがあります。オペレーションを開始すると、ターミナルを閉じてもオペレーションはキャンセルされません。
TTL インデックスを表示する
TTL インデックスを表示する手順は次のとおりです。
MongoDB API
listIndexes() メソッドを使用して、TTL インデックスを表示します。次に例を示します。
db.restaurants.listIndexes()
出力には、TTL インデックスと TTL 以外のインデックスの両方が含まれます。TTL インデックスには expireAfterSeconds オプションが含まれます。
Google Cloud Console
Google Cloud コンソールで [データベース] ページに移動します。
データベースのリストから、必要なデータベースを選択します。
ナビゲーション メニューで [有効期間（TTL）] をクリックします。
コンソールには、データベースの TTL インデックスが表示され、各インデックスのステータスも含まれています。
gcloud
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 が使用されます。
Google Cloud Console
Google Cloud コンソールで [データベース] ページに移動します。
データベースのリストから、必要なデータベースを選択します。
ナビゲーション メニューで [有効期間（TTL）] をクリックします。
[TTL インデックス] テーブルで、TTL インデックスの行を見つけます。このテーブル行で、削除（ゴミ箱）ボタンをクリックします。
[削除] をクリックして確定します。
コンソールの [有効期間（TTL）] ページに戻ります。成功すると、Cloud Firestore がテーブルから TTL インデックスを削除します。
gcloud
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 制御の削除に関する指標を表示できます。Cloud Firestore には、TTL に関する次の指標が用意されています。
| 指標のタイプ | 指標名 | 指標の説明 |
|---|---|---|
| firestore.googleapis.com/document/ttl_deletion_count | 有効期間による削除数 |
TTL インデックスによって削除されたドキュメントの合計数。 |
| firestore.googleapis.com/document/ttl_expiration_to_deletion_delays | 有効期間の期限切れから削除までの遅延 |
TTL インデックスに基づいてドキュメントが期限切れになってから実際に削除されるまでの経過時間。 |
Cloud Firestore の指標を使用してダッシュボードを設定するには、カスタム ダッシュボードを管理するとダッシュボード ウィジェットを追加するをご覧ください。