TTL ポリシーでデータ保持を管理する

このページでは、Google Cloud コンソールと Google Cloud CLI を使用して、有効期間（TTL）ポリシーを構成する方法について説明します。このページを読む前に、Firestore データモデルについて理解しておく必要があります。

有効期間の概要

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

料金

TTL 削除オペレーションは、ドキュメントの削除費用にカウントされます。削除オペレーションの料金については、Firestore の料金をご覧ください。

制限と制約

TTL フィールドとして指定できるのは、1 つのコレクショングループにつき 1 つのフィールドのみです。
合計で 200 個のフィールドレベルの構成が可能です。1 つのフィールド構成に、同じフィールドの構成を複数含めることができます。たとえば、単一フィールドインデックス除外と、同じフィールドに対する TTL ポリシーは、上限に対して 1 つのフィールド構成としてカウントされます。
Datastore モードの Firestore の場合、TTL をエンティティグループによるオプティミスティックの同時実行モードと併用することはできません。同時実行モードをオプティミスティック同時実行モードに変更することを検討してください。

TTL の削除

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

TTL による削除は短時間のプロセスではありません。TTL プロセスにより実際に削除されるまで、期限切れのドキュメントはクエリとルックアップリクエストに引き続き表示されます。TTL では、削除の総所有コストを削減できるというメリットは、削除の適時性との引き換えとなります。データは通常、有効期限が切れた後 24 時間以内に削除されます。
TTL を使用してドキュメントを削除しても、そのドキュメントのサブコレクションは削除されません。
既存のコレクショングループに TTL ポリシーを適用すると、新しい TTL ポリシーに従って期限切れとなったすべてのデータが一括削除されます。この一括削除も即時には行われず、該当するコレクショングループのデータの残量によって決まります。
ドキュメントに以前の有効期限がある場合に、新しい TTL ポリシーをコレクションに追加すると、TTL ポリシーの設定が終了してアクティブになってから 24 時間以内にドキュメントが削除されます。
TTL では、有効期限のタイムスタンプと同じ順序でドキュメントが削除されるとは限りません。
削除はトランザクション的に行われるわけではありません。有効期限が同じドキュメントが同時に削除されるとは限りません。この動作が必要な場合は、クライアントライブラリを使用して削除を行います。
Firestore は、常に最新の TTL フィールドを使用して有効期限を決定します。たとえば、有効期限が切れているが未削除のドキュメントの TTL フィールドを将来の日付に更新すると、そのドキュメントは期限切れにはならず、新しい日付が使用されます。
TTL は他のデータベースアクティビティへの影響を最小限にするように設計されています。TTL による削除は、それよりも低い優先度で処理されます。また、TTL による削除が原因のトラフィックの急増を抑制するための戦略も実施されています。
TTL による削除では、すべてのアクティブなスナップショットリスナーが呼び出され、Cloud Run 関数の Firestore トリガーがトリガーされます。

TTL フィールドとインデックス

TTL フィールドは、インデックス付きにすることも、インデックスなしにすることもできます。ただし、TTL フィールドはタイムスタンプであるため、このフィールドをインデックス付きにすると、トラフィックレートが高い場合にパフォーマンスに影響することがあります。タイムスタンプフィールドをインデックス付きにすると、ホットスポットが発生する可能性があり、これはベストプラクティスに反します。ホットスポットは、狭いドキュメント範囲に対する高頻度の読み取り、書き込み、削除を指します。

デフォルトでは、Cloud Firestore はすべてのフィールドに対して単一のフィールドインデックスを作成します。単一のフィールドインデックスの除外を作成して、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 のロールをご覧ください。

始める前に

gcloud CLI を使用して TTL ポリシーを管理する前に、gcloud components update コマンドを使用して、コンポーネントを利用可能な最新バージョンに更新します。

gcloud components update

TTL ポリシーの作成

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

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

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

TTL フィールドの値は、将来、現在、過去の時刻のいずれかにできます。値が過去の時刻であれば、ドキュメントはすぐに削除できます。たとえば、expireAt フィールドで TTL ポリシーを作成し、それを既存のドキュメントに追加します。
他のデータタイプを使用したり、TTL フィールド値を設定しないと、個々のドキュメントの TTL が無効になります。

TTL ポリシーを作成する手順は次のとおりです。

Google Cloud コンソール

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

[データベース] に移動
データベースのリストから、必要なデータベースを選択します。
ナビゲーションメニューで [有効期間（TTL）] をクリックします。
[ポリシーを作成] をクリックします。
コレクショングループ名とタイムスタンプフィールド名を入力します。
[作成] をクリックします。

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

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
firestore fields ttls update コマンドを使用して、TTL ポリシーを構成します。--async フラグを追加すると、gcloud CLI はオペレーションの完了を待機しません。
```
 gcloud firestore fields ttls update
ttl_field --collection-group=collection_group_name
--enable-ttl 
```

TTL ポリシーの有効化の所要時間

空のデータベースであっても、TTL ポリシーを有効にするために 10 分以上かかることがあります。オペレーションを開始すると、ターミナルを閉じてもオペレーションはキャンセルされません。

TTL ポリシーの表示

TTL ポリシーとそのステータスを表示する手順は次のとおりです。

Google Cloud コンソール

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

[データベース] に移動
データベースのリストから、必要なデータベースを選択します。
ナビゲーションメニューで [有効期間（TTL）] をクリックします。

コンソールには、データベースの TTL ポリシーが表示され、各ポリシーのステータスも含まれています。

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
firestore fields ttls list コマンドを使用して、TTL ポリシーを構成します。次のコマンドを実行すると、すべての TTL ポリシーが一覧表示されます。
```
gcloud firestore fields ttls list
```
特定のコレクショングループの TTL ポリシーを一覧表示するには、次のコマンドを使用します。
```
gcloud firestore fields ttls list  --collection-group=collection_group_name
```

View operation details

You can use the gcloud CLI to view more details about a TTL policy that is in the CREATING state.

Use the operations list command to see all running and recently completed operations:

gcloud firestore operations list

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

TTL ポリシーを無効にする

TTL ポリシーを無効にする手順は次のとおりです。

Google Cloud コンソール

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

[データベース] に移動
データベースのリストから、必要なデータベースを選択します。
ナビゲーションメニューで [有効期間（TTL）] をクリックします。
[TTL ポリシー] テーブルで、TTL ポリシーの行を見つけます。このテーブル行で、削除（ゴミ箱）ボタンをクリックします。
[削除] をクリックして確定します。

コンソールが [有効期間] ページに戻ります。成功すると、Firestore がテーブルから TTL ポリシーを削除します。

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
firestore fields ttls update コマンドを使用して、TTL ポリシーを構成します。--async フラグを追加すると、gcloud CLI はオペレーションの完了を待機しません。
```
gcloud firestore fields ttls update ttl_field --collection-group=collection_group_name --disable-ttl
```

TTL の削除のモニタリング

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

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

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