Disclosure: This AI-assisted technical article was prepared for Cengal, a Firestore developer tool. All examples and original code-drawn illustrations use synthetic data. No Cengal account, subscription or paid product is needed to follow it.

A reported symptom, not a diagnosis of someone else's system

On June 24, 2021, a developer reported on Stack Overflow that deleted team documents left player documents behind, while querying teams did not reveal those missing parents.

That report includes cleanup-function code and later errors. We have not reproduced that entire application or established its complete cause. The narrower behavior is documented by Firebase's deletion guide: a document deletion does not cascade into its subcollections. An absent parent is not returned as a document in a normal parent-collection query.

This is worth checking before treating a remaining child as a failed delete or a stale UI.

Reproduce it with two disposable documents

Use the Node.js server SDK @google-cloud/firestore in a scratch project. Start a local Firestore emulator on 127.0.0.1:8080 with project ID demo-delete-example, following Firebase's emulator connection guide. Set FIRESTORE_EMULATOR_HOST=127.0.0.1:8080 before running this CommonJS script.

const { Firestore } = require('@google-cloud/firestore');
if (process.env.FIRESTORE_EMULATOR_HOST !== '127.0.0.1:8080') {
  throw new Error('This example requires the local Firestore emulator');
}
const db = new Firestore({ projectId: 'demo-delete-example' });

async function run() {
  const team = db.doc('teams/demo');
  const player = team.collection('players').doc('ada');
  await team.set({ name: 'Demo team' });
  await player.set({ name: 'Ada' });

  await team.delete(); // deletes this document, not its descendants
  console.log((await team.get()).exists); // false
  console.log((await player.get()).exists); // true
  console.log((await db.collection('teams').get()).size); // 0
  console.log((await team.collection('players').get()).size); // 1

  await player.delete(); // clean up this one known synthetic child
  console.log((await player.get()).exists); // false
}
run().catch(error => {
  console.error(error);
  process.exitCode = 1;
}).finally(() => db.terminate());

The guard deliberately refuses a different or missing emulator endpoint. The demo- project ID is another boundary. Do not adapt this example by pointing it at a real team or account. If you choose another loopback port, change both the environment value and the guard.

Two paths, two outcomes

The parent teams/demo stores one document's fields. The child teams/demo/players/ada is a separate document at another path. Removing the first does not remove the second. A reference to the child still identifies its path even when the parent document no longer exists.

The empty teams query therefore answers a narrow question: which existing team documents match? It is not an inventory of every descendant stored beneath team paths. Check a known child reference separately when investigating this symptom.

Animation note: this syndicated copy uses an equivalent still. The original article provides the original reaction animation with pause and reduced-motion support.

Choose the intended deletion boundary

If you meant to delete only the parent record, surviving children may be expected. Decide whether the application should keep or expose them; do not infer the intended retention policy from the document hierarchy alone.

If you meant to remove a whole subtree, use a separately designed cleanup operation. Firebase's recursive-deletion solution describes a trusted-server approach and warns about authorization, cost and incomplete work. Review that guidance rather than turning the tiny example above into a general recursive-deletion utility.

For a real cleanup, first inventory the exact project, database and paths. Restrict who can request it, coordinate other writers, choose recovery procedures, and make progress and failures visible. Reading and deleting a changing dataset is not automatically atomic: another writer can create children while cleanup runs. A successful parent delete alone proves nothing about completion of a larger cleanup.

What the local test actually proved

On October 22, 2026, nine assertions passed using Firestore emulator 1.22.0 and Node server SDK 7.11.6 on loopback with a demo- project. They checked both documents before deletion; the absent parent and retained child afterward; an empty parent query; the child query and collection-group result; explicit child cleanup; and a second parent delete leaving it absent.

This is a synthetic test of document/path semantics. It does not test production IAM, billing, client Security Rules, a recursive cleanup service, concurrent cleanup, or Cengal's UI. Server SDK access does not validate mobile/web Security Rules. Different deletion tools can deliberately implement recursion, so check the exact operation you used rather than generalizing from its button label.

One question for your data model

When a parent record is removed, which child records should survive—and where is that retention decision enforced?

Changing theme should not require rebuilding an entire preferences map. But the shape of a Firestore update determines whether you replace that map or update one leaf inside it.

Disclosure: This is an AI-assisted technical article prepared for Cengal, a Firestore developer tool. The examples and original code-generated illustrations use synthetic data, not customer records. You do not need Cengal or a paid product to use the solution.

A real report, not a newly discovered incident

On March 7, 2018, a developer reported on Stack Overflow that updating a map's test field also removed its sibling test2. Their shown update supplied the parent field with a new object.

That code is consistent with the map-replacement behavior described in Firebase's nested-field guidance. This does not establish the complete cause of that developer's environment, nor show how often the issue occurs today. It gives us a concrete behavior to reproduce rather than a reason to blame a console, cache or SDK bug.

Reproduce the distinction with one disposable document

The following is Node.js server SDK code using @google-cloud/firestore, not the modular Web SDK or Flutter API. Run it against a local emulator, never a real collection you care about. Install the SDK in your own scratch project and start a Firestore emulator on 127.0.0.1:8080 with project ID demo-map-example first. Server libraries do not exercise client Security Rules.

const { Firestore } = require('@google-cloud/firestore');

// Fail closed rather than accidentally using production credentials.
if (process.env.FIRESTORE_EMULATOR_HOST !== '127.0.0.1:8080') {
  throw new Error('Start the local emulator and set FIRESTORE_EMULATOR_HOST');
}
const db = new Firestore({ projectId: 'demo-map-example' });
const ref = db.collection('profiles').doc('demo');
const seed = {
  name: 'Ada',
  preferences: { theme: 'dark', notifications: true }
};

async function run() {
  await ref.set(seed);
  await ref.update({ preferences: { theme: 'light' } });
  console.log((await ref.get()).data());
  // { name: 'Ada', preferences: { theme: 'light' } }

  await ref.set(seed); // reset only this disposable fixture
  await ref.update({ 'preferences.theme': 'light' });
  console.log((await ref.get()).data());
  // { name: 'Ada', preferences: { theme: 'light', notifications: true } }
}
run()
  .catch(error => {
    console.error(error);
    process.exitCode = 1;
  })
  .finally(() => db.terminate());

Set FIRESTORE_EMULATOR_HOST=127.0.0.1:8080 in that scratch project's shell before running. If your emulator uses another port, change both the environment value and the guard. The demo- project name and explicit local-host guard are deliberate safety boundaries.

The update key defines the boundary

Original AI-assisted, code-generated diagram for this article. Both branches start from the same synthetic document.

preferences targets the map value. The supplied { theme: 'light' } becomes that value; omitted map siblings do not survive. The unrelated top-level name still survives because this is an update of preferences, not a replacement of the whole document.

'preferences.theme' targets one nested field. Firestore changes that leaf without replacing the surrounding map. Quotes matter here: this is a string field path in the update object.

Original AI-assisted, code-generated humor illustration; no third-party clips or likenesses. This static equivalent preserves the joke without uncontrolled motion. The original article has the animation with reduced-motion fallback and Pause/Resume controls.

What if a field name itself contains a dot?

A literal field name a.b is not the same as a nested a map containing b. For the Node server SDK, pass separate literal segments to FieldPath, using the alternating field-path/value update overload:

Inside an async function using the existing ref:

const { FieldPath } = require('@google-cloud/firestore');
await ref.update(new FieldPath('preferences', 'a.b'), true);
// preferences now includes the literal key "a.b": true

await ref.update({ 'preferences.a.b': true });
// This instead targets preferences -> a -> b.

Do not put a FieldPath object into a computed JavaScript object key; that coerces it to a string. Do not concatenate arbitrary field names into dotted paths if those names may contain dots. Use the SDK's field-path API appropriate to your platform.

A small patch is not a concurrency strategy

Suppose another writer turns notifications off. A subsequent theme-only leaf update leaves that newer notifications value alone. A stale whole-map update can put the old notifications value back.

That does not make leaf updates conflict-proof. Two writers setting the same leaf can still overwrite one another. If a write must depend on values you read, evaluate a Firestore transaction and its retry behavior. A field path is not undo, a backup, a restore mechanism or an array-index editing API.

Also, update() requires an existing document. Do not silently switch to a create-capable write just to make a missing-document error disappear; first decide whether creation is actually intended.

What was tested—and what was not

On October 21, 2026, the accompanying local test used Firestore emulator 1.22.0 and Node server SDK 7.11.6 with a demo- project on loopback. Seven assertions passed: parent-map replacement; leaf-path preservation; literal dotted names; nested dotted paths; rejection of an update to a missing document; preservation of a newer sibling by a leaf patch; and overwriting of that sibling by a stale whole map.

Each case reset synthetic data. The two-writer cases used deterministic sequential interleavings, not a concurrency stress test. These results validate the example's map/path semantics, not production IAM, client Rules, indexes, billing, or Cengal's editor. A full-document JSON save in any tool is not automatically equivalent to a leaf-path SDK update.

Before changing a real document

1. Identify the exact field you intend to change, and whether any segment contains a literal dot.
2. Reproduce the update shape with disposable emulator data.
3. Read the result back and check the fields you expected to remain.
4. Handle missing documents and read-dependent writes deliberately. Apply your normal access controls and recovery practices before production changes.

Which boundary has caused more surprises in your application: replacing a nested map, handling literal dotted field names, or coordinating two writers? A small anonymized before/update/after example makes the distinction easier to discuss.

Examples use synthetic data. AI assistance was used in preparation; verification scope is stated below. Originally published on Cengal.

orderBy() doesn't only arrange the results. It also excludes documents that don't have the ordered field. Firebase calls this out in its ordering documentation, but it's an easy detail to miss when the same collection looked fine a moment earlier.

The document hasn't necessarily been deleted. It may no longer qualify for that particular query.

The sort didn't delete the task—it stopped inviting it. Original six-second sample-data GIF, created with AI assistance, not an app screenshot. The still tells the same story.

Original Cengal sample-data still illustration, created with AI assistance, not an app screenshot.

A small example you can reason about

Imagine a task collection with these three synthetic documents:

Start with an open-task query. This example uses the Node.js server SDK; don't mix its syntax with the Web SDK's modular API.

const tasks = db.collection("orderbyExampleTasks");
const openTasks = tasks.where("status", "==", "open");

const before = await openTasks.get();
console.log(before.docs.map(doc => doc.id).sort());
// ["review", "triage"]

Now add the sort:

const after = await openTasks.orderBy("priority").get();
console.log(after.docs.map(doc => doc.id));
// ["triage"]

review still has status: "open", but it has no priority field. Adding the sort excludes it. A larger limit won't bring it back, because the missing field—not the page size—is the issue.

review at the query door: “I’m still in the database, you know.” Original reaction GIF, created with AI assistance, not an app screenshot.

We ran these examples against synthetic data in the local Standard-edition Firestore emulator. The baseline returned all three IDs, the open-status query returned review and triage, and the ordered open-status query returned only triage, both with and without a limit of two. The runnable fixture and exact environment are recorded in our publishing evidence. This checks query behavior, not production index requirements, permissions, billing, or an application UI.

Check the document, not just the table

Remove the ordering temporarily and run a small, bounded read against the same project, database, and collection. If the document returns, inspect that record's fields directly.

Look for an absent key, a slightly different field name, or a value written somewhere else in a nested map. A column displayed for other rows isn't proof that every document has that field. And a blank table cell isn't enough to tell you whether a field is missing, null, or simply not shown by that view.

Keep errors visible during this check. A successful query with one result is different from a permission or missing-index error. Don't catch every exception and turn it into an empty array—that makes separate problems look alike.

Decide what the field means before filling it in

There are two reasonable questions to ask:

• Should every task have a priority? If so, check the writers that create tasks, then plan a reviewed correction for existing records.
• Is priority genuinely optional? If so, an ordered query over that field may not be the right way to fetch every open task.

Don't assign a value to every production document just to make a screen look complete. A default priority changes the meaning of the data. Work out the intended behavior first, and test it with a small fixture.

If you change the query's filters or ordering, reset its pagination too. A cursor from the previous query is another reason a page can look incomplete. Firebase's cursor guidance explains how cursor values relate to the query's ordering.

Where Cengal can help

If you'd rather inspect the records visually, Cengal can browse Firestore collections, show document fields and types, and build bounded queries on Mac. You can compare the result with and without the sort, then inspect the document that drops out. Core browsing and querying are available on Free; macOS 14 or later is required.

If the data needs an edit, Cengal lets you stage it and review the change before applying it. That doesn't make a schema decision for you, fix Security Rules, create an index, or remove Firestore read costs. The useful part here is making the stored record and intended change easier to inspect.

For the related workflow, see Cengal queries and missing composite-index errors. The same diagnostic works in your SDK or Firebase Console; you don't need a particular GUI to use it.

This checklist covers Firestore’s Core query API, with examples verified in a local Standard-edition emulator. It does not cover MongoDB-compatible queries or Firestore Pipeline operations.

Disclosure: This article was prepared for Cengal, a native Mac workspace for Firestore. AI assistance was used in drafting and automated verification. The sample cases were executed against synthetic emulator data, not a customer database or a live Cengal session.

1. Keep errors separate from empty results

Avoid turning every exception into an empty array:

try {
  const snapshot = await query.get();
  console.log({ empty: snapshot.empty, size: snapshot.size });
} catch (error) {
  console.error(error.code, error.message);
  throw error;
}

This example uses the Node.js server SDK. Adapt the syntax to your client SDK rather than mixing APIs.

A permissions error is not evidence that no matching documents exist. Likewise, an index error should remain visible. Diagnose the actual error before rewriting the query.

For mobile and web clients, Security Rules are not a post-query filter. A query that could return unauthorized documents can be rejected as a whole. Do not make the database public to investigate an empty screen. See Firebase’s secure-query guidance.

2. Establish the exact target

Write down:

• Project ID and database ID.
• Emulator versus deployed database.
• Full collection path, including parent document IDs.
• Collection query versus collection-group query.
• The identity and SDK used for the read.

A query against orders does not search every nested collection named orders. A different database or environment can also contain a perfectly valid—but empty—collection.

Use a bounded baseline read on the intended collection. If that returns nothing, investigate the target before adding filters. Avoid downloading an entire production collection just to debug a predicate.

3. Use a tiny fixture to test assumptions

Here is the complete synthetic dataset used for the checks below:

const rows = {
  a: {
    status: "active",
    score: 10,
    tags: ["red"],
    optional: null
  },
  b: {
    status: "active",
    score: "10",
    tags: ["blue"]
  },
  c: {
    status: "Active",
    score: 20,
    tags: "red"
  },
  d: {
    status: "archived",
    score: 30,
    tags: ["red"],
    optional: "present"
  }
};

Each key is a document ID in a collection called queryChecklist. Notice the intentional inconsistencies: capitalization, a numeric string, a scalar where other documents have arrays, and missing fields.

With a Node server-SDK collection reference named c, these were the observed results:

Call .get() on each query to execute it. Result IDs in the table are sorted for comparison; the table is not promising a particular query result order.

The tests used Firestore emulator 1.22.0 in Standard edition with @google-cloud/firestore 7.11.6. These are query-semantics checks—not production index, authorization, billing, or application-UI tests. Server SDK access also does not reproduce mobile/web Security Rules behavior.

Original Cengal animation, created with AI assistance from the synthetic fixture above—not an app recording. Document b has not vanished; it is just off this query’s guest list. The static illustration in section 5 provides a non-animated explanation.

4. Add constraints one at a time

Start with the baseline. Then restore one filter, run it, and record the result before restoring the next.

The conflicting-status example is deliberately simple: both predicates can work separately, but no document can have both scalar values at once.

Check the actual stored value and type. In this fixture, 10 and "10" produce different matches. So do "active" and "ACTIVE". A UI rendering both values similarly does not make them interchangeable.

For arrays, distinguish “the field contains this element” from “the whole field equals this value.” Our tags examples return different documents for precisely that reason.

Firebase documents the relevant operators in its query reference.

5. Remove ordering while diagnosing missing documents

The active-status filter returns a and b. Adding orderBy("optional") leaves only a, because b has no optional field.

Sorting can therefore change which documents qualify—not merely their display order. Firebase explicitly documents that ordering excludes documents missing the ordered field in order and limit data.

Do not immediately backfill a production field. First confirm whether the field is genuinely required by your data model and query.

Original Cengal sample-data illustration, not an app screenshot. This separate open-status/priority example illustrates the same missing-field behavior. Source: Cengal’s ordering guide.

6. Treat missing fields and null as different states

Document a has optional: null. Documents b and c have no optional field.

In this fixture, equality with null returns only a. The negative-membership query does not act as “everything except this value, including missing fields.” Adding null to the not-in comparison list produces no matches.

Inspect a representative document rather than guessing how absent values are represented.

7. Reset pagination before changing the data

A cursor can legitimately describe a page after the final result.

Remove the cursor and use a small, positive limit while checking the first page. Rebuild pagination state after changing filters or ordering. Confirm that cursor values correspond to the current ordering rather than a previous query.

The final fixture check intentionally places the cursor beyond the available ordered values. It returns an empty page even though the collection contains four documents.

A practical stopping point

Before changing anything, you should be able to answer:

1. Did the request succeed?
2. Is this the intended project, database, and collection?
3. Does a bounded baseline read return documents?
4. Which single constraint first removes the expected document?
5. Are field types, missing values, ordering, and pagination consistent with that constraint?

That is a useful debugging result even before a fix: it turns “Firestore is empty” into a specific, reproducible explanation.

If you prefer inspecting documents visually, Cengal is one option for browsing and querying Firestore on Mac, requiring macOS 14 or later. The same checklist works with your SDK or Firebase console; no particular GUI is required.