Local Query Indexes, Cache Growth, User Sign-Out / Data Clearing, and Offline Performance

Learning outcomes

1. AtlasMart problem: the catalog is cached, but offline filtering gets slower

A field salesperson uses AtlasMart offline for days. The device accumulates hundreds or thousands of cached catalog documents. By default, the Firestore SDK can scan cached documents to answer an offline query. That is correct but may become slower as the cache grows. Persistent cache supports local query indexes so the SDK can accelerate repeated offline queries.

2. Automatic local indexing is disabled by default

With persistent cache enabled, obtain the SDK’s persistent cache index manager. Automatic index creation must be enabled each app start. The SDK then decides which cached collections/queries justify local indexes. Manual setIndexConfiguration() APIs are obsolete; prefer automatic index creation for current code.

import {  getPersistentCacheIndexManager,  enablePersistentCacheIndexAutoCreation,  disablePersistentCacheIndexAutoCreation,  deleteAllPersistentCacheIndexes,  getDocs, query, collection, where, orderBy, limit} from "https://www.gstatic.com/firebasejs/12.19.0/firebase-firestore.js";const manager=getPersistentCacheIndexManager(db);if(!manager) throw new Error("Persistent cache is required for local query indexes");const q=query(collection(db,"catalogItems"),  where("category","==","camera"),orderBy("stock","asc"),limit(50));async function timed(label){  const t0=performance.now();  const snap=await getDocs(q);  const ms=performance.now()-t0;  console.log(label,{ms,count:snap.size,fromCache:snap.metadata.fromCache});}await disableNetwork(db);await timed("offline-before-auto-index");enablePersistentCacheIndexAutoCreation(manager); // enable on every app start// Run the query repeatedly / allow the SDK to decide when indexing is useful.for(let i=0;i<8;i++) await timed(`offline-after-enable-${i}`);// For a reset experiment only:// disablePersistentCacheIndexAutoCreation(manager);// deleteAllPersistentCacheIndexes(manager);

Do not copy a single elapsed-time number into architecture documentation. Record fixture size, browser/device, warm/cold state, number of repetitions and cache mode. The first runs may include setup/index-building work; later runs may differ.

3. Build enough cached data to make the mechanism visible

import { initializeApp } from "firebase-admin/app";import { getFirestore } from "firebase-admin/firestore";process.env.FIRESTORE_EMULATOR_HOST="127.0.0.1:8080";process.env.GCLOUD_PROJECT="demo-atlasmart-firestore";initializeApp({projectId:"demo-atlasmart-firestore"});const db=getFirestore();const writer=db.bulkWriter();for(let i=0;i<1500;i++){  const id=`offline-${String(i).padStart(4,"0")}`;  writer.set(db.collection("catalogItems").doc(id),{    sellerId:`seller-${i%20}`,    category:["camera","hub","cable","sensor"][i%4],    stock:(i*17)%101,    priceCents:1000+(i%250)*37,    offlineFixture:true  });}await writer.close();console.log("seeded 1500 deterministic offline fixtures");

Seed on the emulator, then while online fetch the fixture collection so documents enter the persistent cache. Disconnect the SDK network and run the filtered/ordered query. The experiment is local and free; it does not claim production query latency or billing.

4. Cache growth is bounded by a garbage-collection target, not an exact limit

const db=initializeFirestore(app, {  localCache: persistentLocalCache({    cacheSizeBytes: 80 * 1024 * 1024,    tabManager: persistentMultipleTabManager()  })});// The threshold is approximate; cleanup is attempted after exceeding it.// CACHE_SIZE_UNLIMITED disables garbage collection and should be a deliberate choice.

5. Sign-out and emulator reset need a cache plan

The Firestore emulator clears backend contents when it shuts down, but client offline cache is not automatically cleared. If a test restarts the emulator and then sees old data from persistent cache, that is a test-isolation bug—not proof that the emulator retained data. Either disable persistence for tests that do not test offline behavior, or terminate/clear the client cache between scenarios.

6. Wrong approach: “enable every local index and disable cache cleanup”

Local indexes are a performance tool with device resource cost. Unlimited cache plus aggressive indexing can increase storage footprint and privacy exposure. Start from measured offline UX: how many cached documents, which queries, which devices, and how long users remain offline. Let the SDK’s automatic indexing decide when indexes are useful and retain an explicit reset path for tests.

Production judgment

Benchmark local query performance separately from server query performance. Track cache mode, fixture cardinality and device class. A p95/p99 local-query target is meaningful only with controlled device/cache conditions. Do not infer server read cost from local query time, and do not infer local speed from server Query Explain. Lesson 5 combines cache, restart, conflict, Rules changes and reconnect into one end-to-end failure test.

Knowledge check

1. Are persistent-cache query indexes the same as Firestore server indexes?
2. Is automatic local index creation enabled automatically?
3. Why seed many documents in the emulator?
4. Does the cache-size threshold guarantee the cache never exceeds that size?
5. Why can emulator tests show stale data after backend reset?

Summary and next step

Persistent local indexes optimize the client cache, not the server. Lesson 5 now runs the complete offline failure matrix, including a Rules change while a write is pending.

Authoritative references

• Access data offline — offline query behavior and automatic persistent-cache indexing.
• JavaScript Firestore API — persistent cache index manager and automatic index functions.
• PersistentCacheIndexManager — current local-index manager API.
• PersistentCacheSettings — cache-size threshold and tab manager.
• Firestore Emulator Suite — client cache caveat after emulator shutdown/reset.