Best practices

Use the best practices listed here as a quick reference when building an application that uses Cloud Firestore.

Database location

When you create your database instance, select the database location closest to your users and compute resources. Far-reaching network hops are more error-prone and increase query latency.

To maximize the availability and durability of your application, select a multi-region location and place critical compute resources in at least two regions.

Select a regional location for lower costs, for lower write latency if your application is sensitive to latency, or for co-location with other GCP resources.

Document IDs

• Avoid the document IDs . and ...
• Avoid using / forward slashes in document IDs.

• Do not use monotonically increasing document IDs such as:

  • Customer1, Customer2, Customer3, ...
  • Product 1, Product 2, Product 3, ...

  Such sequential IDs can lead to hotspots that impact latency.

Field Names

• Avoid the following characters in field names because they require extra escaping:

  • . period
  • [ left bracket
  • ] right bracket
  • * asterisk
  • ` backtick

Indexes

• Avoid using too many indexes. An excessive number of indexes can increase write latency and increases storage costs for index entries.

• Be aware that indexing fields with monotonically increasing values, such as timestamps, can lead to hotspots which impact latency for applications with high read and write rates.

Index exemptions

For most apps, you can rely on automatic indexing as well as any error message links to manage your indexes. However, you may want to add single-field exemptions in the following cases:

Read and write operations

• Avoid writing to a document more than once per second. For more information, see Updates to a single document.

• Use asynchronous calls where available instead of synchronous calls. Asynchronous calls minimize latency impact. For example, consider an application that needs the result of a document lookup and the results of a query before rendering a response. If the lookup and the query do not have a data dependency, there is no need to synchronously wait until the lookup completes before initiating the query.

• Do not use offsets. Instead, use cursors. Using an offset only avoids returning the skipped documents to your application, but these documents are still retrieved internally. The skipped documents affect the latency of the query, and your application is billed for the read operations required to retrieve them.

Transactions retries

The Cloud Firestore SDKs and client libraries automatically retry failed transactions to deal with transient errors. If your application accesses Cloud Firestore through the REST or RPC APIs directly instead of through an SDK, your application should implement transaction retries to increase reliability.

Realtime updates

For the best snapshot listener performance, keep your documents small and control the read rate of your clients. The following recommendations provide guidelines for maximizing performance. Exceeding these recommendations can result in increased notification latency.

Designing for scale

The following best practices describe how to avoid situations that create contention issues.

Updates to a single document

You should not update a single document more than once per second. If you update a document too quickly, then your application will experience contention, including higher latency, timeouts, and other errors.

High read, write, and delete rates to a narrow document range

Avoid high read or write rates to lexicographically close documents, or your application will experience contention errors. This issue is known as hotspotting, and your application can experience hotspotting if it does any of the following:

• Creates new documents at a very high rate and allocates its own monotonically increasing IDs.

  Cloud Firestore allocates document IDs using a scatter algorithm. You should not encounter hotspotting on writes if you create new documents using automatic document IDs.

• Creates new documents at a high rate in a collection with few documents.

• Creates new documents with a monotonically increasing field, like a timestamp, at a very high rate.

• Deletes documents in a collection at a high rate.

• Writes to the database at a very high rate without gradually increasing traffic.

Ramping up traffic

You should gradually ramp up traffic to new collections or lexicographically close documents to give Cloud Firestore sufficient time to prepare documents for increased traffic. We recommend starting with a maximum of 500 operations per second to a new collection and then increasing traffic by 50% every 5 minutes. For instance, you can use this ramp up schedule to grow your read traffic to 740K operations per second after 90 minutes. You can similarly ramp up your write traffic, but keep in mind the Cloud Firestore Standard Limits. Be sure that operations are distributed relatively evenly throughout the key range. This is called the "500/50/5" rule.

Migrating traffic to a new collection

Gradual ramp up is particularly important if you migrate app traffic from one collection to another. A simple way to handle this migration is to read from the old collection, and if the document does not exist, then read from the new collection. However, this could cause a sudden increase of traffic to lexicographically close documents in the new collection. Cloud Firestore may be unable to efficiently prepare the new collection for increased traffic, especially when it contains few documents.

A similar problem can occur if you change the document IDs of many documents within the same collection.

The best strategy for migrating traffic to a new collection depends on your data model. Below is an example strategy known as parallel reads. You will need to determine whether or not this strategy is effective for your data, and an important consideration will be the cost impact of parallel operations during the migration.

Parallel reads

To implement parallel reads as you migrate traffic to a new collection, read from the old collection first. If the document is missing, then read from the new collection. A high rate of reads of non-existent documents can lead to hotspotting, so be sure to gradually increase load to the new collection. A better strategy is to copy the old document to the new collection then delete the old document. Ramp up parallel reads gradually to ensure that Cloud Firestore can handle traffic to the new collection.

A possible strategy for gradually ramping up reads or writes to a new collection is to use a deterministic hash of the user ID to select a random percentage of users attempting to write new documents. Be sure that the result of the user ID hash is not skewed either by your function or by user behavior.

Meanwhile, run a batch job that copies all your data from the old documents to the new collection. Your batch job should avoid writes to sequential document IDs in order to prevent hotspots. When the batch job finishes, you can read only from the new collection.

A refinement of this strategy is to migrate small batches of users at a time. Add a field to the user document which tracks migration status of that user. Select a batch of users to migrate based on a hash of the user ID. Use a batch job to migrate documents for that batch of users, and use parallel reads for users in the middle of migration.

Note that you cannot easily roll back unless you do dual writes of both the old and new entities during the migration phase. This would increase Cloud Firestore costs incurred.