This page describes how to use the Google Cloud console and theGoogle Cloud CLIto configure time to live (TTL) policies.

Time to live overview

Use TTL policies to automaticallyremove stale data from your databases. A TTL policy designates a given field asthe expiration time for documents in a given collection. With TTL, you candecrease storage costs by cleaning out obsolete data. Data is typically deletedwithin 24 hours after its expiration date.

Pricing

TTL delete operations count towards your document delete costs. For pricingof delete operations, seeCloud Firestore Enterprise edition pricing.

Limits and constraints

• You can mark only one field per collection as a TTL field.
• You can have a maximum of 500 field-level TTL configurations.

TTL deletion

Note the following key behaviors of TTL-driven deletion:

• Deletion through TTL is not an instantaneous process. Expired documentscontinue to appear in queries and lookup requests until the TTL processactually deletes them. TTL trades deletion timeliness for the benefit ofreduced total cost of ownership for deletions.Data is typically deleted within 24 hours after its expiration date.

• Applying a TTL policy on an existing collection results in a bulkdeletion of all expired data according to the new TTL policy. Notethat this bulk deletion is also not instantaneous and depends on how much dataexists for that collection.

• If a document has an expiration time in the past and you add a new TTL policyto the collection, the document will be deleted within 24 hoursof when the TTL policy finishes setup and becomes active.

• TTL does not necessarily delete documents in the same order as theirexpiration timestamps.

• Deletions are not done transactionally. Documents with the same expirationtime are not necessarily deleted at the same time. If you require thisbehavior, perform the deletions using a client library.

• Cloud Firestore will always honor the latest TTL field to determine theexpiration. For example, if an expired but not-yet-deleted document has itsTTL field updated to a later date, the document won't be expired and thenew date will be used.

• Cloud Firestore expires a document only when the TTL field is set to either aDate and time/BSON Date value or anArray value containing aDate and time/BSON Date value. Leave the field absent or set to avalue likenull to disable expirations on a per-document basis.

• TTL is designed to minimize impact on other database activities. Deletionsdriven by TTL are treated with a lower priority. Other strategies arealso in place to smooth out traffic spikes from TTL-driven deletes.

TTL fields and indexes

A TTL field can be indexed or unindexed. However, because a TTL field is atimestamp, indexing the field can affect performance at higher traffic rates.Indexing a timestamp field can createhotspots which is against best practices. Hotspots arehigh read, write, and delete rates to a narrow document range.

Permissions

The principal configuring a TTL policy requires the following permission in theproject:

• Viewing TTL policies requires thedatastore.indexes.listanddatastore.indexes.get permissions.
• Modifying TTL policies requires thedatastore.indexes.updatepermission.
• Checking the status of TTL operations requiresdatastore.operations.list anddatastore.operations.get.

For roles that assign these permissions, seeCloud Firestore Identity and Access Management roles.

Before you begin

Before you use thegcloud CLI to manage TTL policies, use thegcloud components updatecommand to update components to the latest available version:

gcloudcomponentsupdate

Create a TTL policy

When you create a TTL policy, you designate a document field as the expirationtime for documents in a collection.

TTL uses a specified field to identify documents that are eligible for deletion.The TTL field must be set to either aTimestamp/BSON Date value or anArray valuecontaining aTimestamp/BSON Date value. You can select a field thatalready exists or you can designate a field that you plan to add later.

TTL policy enablement duration

Even on an empty database, it can take ten minutes or more to enable a TTLpolicy. Once you start an operation, closing the terminal does not cancel theoperation.

View TTL policies

To view TTL policies and their statuses, follow these steps:

View operation details

You can use thegcloud CLI to view more details about a TTL policythat is in theCREATING state.

Use theoperations list command to see all running andrecently completed operations:

gcloud firestore operations list

The response includes an estimate of the operation's progress.

Disable a TTL policy

To disable a TTL policy, follow these steps:

Monitor TTL deletions

You can useCloud Monitoring to view metrics about TTL-driven deletions.Cloud Firestore provides the following metrics for TTL:

To set up a dashboard withCloud Firestore metrics, seemanage custom dashboard andadd dashboard widgets.