How the cache is updated
- When you read a document by ID through the cache and it is not there, it is fetched from Firestore and cached;
- The Firestore listener updates the cache when a document changes, whether the change came from your application or from elsewhere;
- Preloading at startup.
Cached results are eventually consistent: they reflect the last state the listener delivered, so a write may take a moment to show up. Do not cache data that must be read at strong consistency. This holds for pipeline and SQL reads that the cache answers too.
Firestore also reports how many documents a target matches. When that disagrees with what a preloaded collection holds - which means changes were missed, typically deletes that happened while the listener was disconnected - the cache drops the collection and has Firestore replay it. The count is only compared when it can be trusted: a collection the cache expires entries from, or fills lazily, is never checked this way.
When Firestore resets or removes a listener target - after a reconnect, or when a stored resume
token has expired - the cache drops what it holds for that collection and Firestore replays it.
While that replay is in progress the collection stops answering list and query from the cache:
read_through_cache falls back to Firestore, and read_cached_only returns a CacheError rather
than a listing that looks complete but is not.
On the Enterprise edition
The listener that updates the cache needs real-time updates on an Enterprise edition database, a setting chosen when the database is created, see Caching.