Get Documents, Create / Set / Merge, Update, Delete, and Understand Missing vs Null Fields

Learning outcomes

AtlasMart now has a stable access-pattern model, but CRUD bugs can still destroy that model. A profile patch can accidentally erase preferences, an update can fail because the document never existed, a nullable field can be confused with an absent field, and a server delete can leave orphaned subcollection data. This lesson treats every write method as a state transition with explicit preconditions rather than as interchangeable vocabulary.

1. Three different absences: document missing, field missing, field null

Firestore does not have one universal “empty” state. A missing document means a document reference names a location for which no document exists; a document snapshot reports that state separately from its data. An absent field means the document exists but the field path is not present. A null field is present and stores the Firestore null value. Those distinctions affect queries, converters, validation, patch semantics, and product meaning.

For AtlasMart, phoneNumber: null can mean “the user explicitly has no phone number,” while a missing phoneNumber can mean “this v1 profile predates the field.” If a converter collapses both to JavaScript undefined, the application loses migration information. Conversely, writing JavaScript undefined is not a portable Firestore data contract; represent optionality deliberately.

2. Get, create, set, merge, and update have different contracts

A read returns a snapshot, not proof that the document exists. A full set is an upsert-like replacement at a known path: if the document is absent it is created; if present its document fields are replaced by the supplied document unless merge semantics are requested. set(..., { merge: true }) preserves omitted fields, but an explicitly supplied map can still replace nested map content depending on the write shape. update patches named fields and fails if the target document does not exist. Server libraries additionally expose create(), which fails if the target already exists.

import { doc, getDoc, setDoc, updateDoc } from "firebase/firestore";const ref = doc(db, "profiles", "u-alice");await setDoc(ref, { displayName: "Alice", locale: "en", schemaVersion: 1 });console.log("seed", (await getDoc(ref)).data());await setDoc(ref, { locale: "fa", schemaVersion: 1 }, { merge: true });console.log("merge", (await getDoc(ref)).data());await updateDoc(ref, { "preferences.theme": "dark" });console.log("patch", (await getDoc(ref)).data());// Deliberate failure: update requires the target document to exist.await updateDoc(doc(db, "profiles", "u-missing"), { locale: "en" });

3. Field deletion and document deletion are not the same lifecycle operation

Deleting one field uses a field-deletion sentinel in an update. That removes the field path while preserving the document. Deleting a document removes that document, but it does not recursively delete documents in subcollections. A path like profiles/u-alice/private/audit can remain reachable after profiles/u-alice is deleted. Therefore “delete profile” is a product/lifecycle workflow, not just one deleteDoc() call.

import { deleteDoc, deleteField, doc, setDoc, updateDoc } from "firebase/firestore";const ref = doc(db, "profiles", "u-alice");await setDoc(ref, { displayName: "Alice", phoneNumber: null, legacyAlias: "alice-1" });await updateDoc(ref, { legacyAlias: deleteField() }); // field becomes absentawait deleteDoc(ref);                                // document becomes absent// Any subcollection documents under profiles/u-alice are separate documents.// Recursive lifecycle cleanup must be designed and executed deliberately.

4. Preconditions turn “last writer wins” into an explicit conflict

When a trusted service must change a document only if it has not changed since a prior read, use a conditional write rather than “read, compare in JavaScript, then blindly update.” Firestore's precondition model can require existence/nonexistence or a matching update time. In the Node server library, a document snapshot exposes updateTime; update and delete accept a precondition. This is useful for optimistic concurrency on a single document when a full transaction is unnecessary.

import { initializeApp } from "firebase-admin/app";import { getFirestore } from "firebase-admin/firestore";initializeApp({ projectId: "demo-atlasmart-firestore" });const db = getFirestore();const productRef = db.doc("products/p-1001");// create() succeeds only if the document does not already exist.await productRef.create({ name: "Trail Camera", priceCents: 12990, schemaVersion: 1 });const before = await productRef.get();const observedUpdateTime = before.updateTime;await productRef.update(  { priceCents: 12490 },  { lastUpdateTime: observedUpdateTime });// If another writer modifies the document after the read, the same precondition fails.

A precondition does not authorize the business action. The Admin/server path is privileged, so the service must still decide whether the authenticated caller is allowed to change the price. A successful update-time match proves freshness relative to one observed version, not that the price itself is valid.

5. Hands-on lab: CRUD state matrix

Continue the same local AtlasMart workspace. Keep firebase emulators:start --only auth,firestore running. Admin/server examples set FIRESTORE_EMULATOR_HOST=127.0.0.1:8080 and GCLOUD_PROJECT=demo-atlasmart-firestore; browser examples connect the modular Web SDK explicitly to the Firestore/Auth emulators. Use only synthetic Chapter 04 documents such as profiles/u-alice, products/p-1001, crudOperations/<operationId>, and named test users. Cleanup must target only those paths.

Case A: GET missing profiles/u-missing -> snapshot missing; no fabricated empty objectCase B: SET full profile -> document exists with exact canonical fieldsCase C: SET merge locale -> displayName remains; locale changesCase D: UPDATE nested field -> target must exist; only named path changesCase E: store phoneNumber=null -> field is present and explicitly nullCase F: deleteField(phoneNumber) -> field absent, document still existsCase G: Admin create same product twice -> first creates; duplicate create failsCase H: Admin update with stale lastUpdateTime -> conditional write failsCase I: delete profile -> parent absent; prove any seeded subcollection doc is separate

For each case, capture the document path, client/server identity, operation name, expected before state, expected after state, and error category. Do not assert exact emulator wording as a timeless API; assert the semantic outcome. Then reset only the Chapter 04 fixtures.

6. Deliberately wrong approach: blind replacement as “update”

Suppose the UI edits only locale but calls full setDoc(ref, { locale: "fa" }). The write can erase displayName, preferences, schemaVersion, and any server-managed fields because the code supplied a replacement document. The fix is not “always use merge.” The fix is to choose the operation that matches the contract: full set only when the caller owns the complete canonical representation; merge/update for controlled patches; server-side conditional writes or transactions for read-dependent invariants.

The same discipline applies to delete. “The document disappeared” is not enough evidence for a privacy/lifecycle requirement if subcollections, projections, exports, or backups remain.

Knowledge check

Summary and next step

CRUD method names now map to explicit state transitions: snapshots prove existence, null is not absence, full set is not a patch, update requires an existing target, field deletion is not document deletion, and server preconditions can surface concurrent changes. Next, apply the same precision to nested field paths and atomic transforms.

Next: Field Paths, Nested Updates, Array Operations, Increment, Server Timestamps, and Atomic Field Transforms.

Authoritative references

• Add data to Cloud Firestore — Official set, merge, update, nested field, server timestamp, array transform, and increment semantics.
• Get data with Cloud Firestore — Document snapshots, existence checks, and custom-object conversion.
• Delete data from Cloud Firestore — Document deletion, field deletion, collection deletion, and subcollection caveats.
• Cloud Firestore data model — Path hierarchy and the warning that deleting a document does not delete its subcollections.
• Secure data in Cloud Firestore — Mobile/web Security Rules versus server IAM trust paths.
• Security Rules conditions — Request/resource validation and explicit server-library bypass guidance.
• Test Security Rules with Emulator Suite — Deterministic local Rules testing.
• Transactions and batched writes — Retry behavior and when read-dependent writes require transactions.
• Firestore REST Precondition — Conditional existence/update-time semantics.
• Set up the Firebase Admin SDK — Privileged server setup, ADC, and current Node.js runtime requirement.
• Firebase JavaScript SDK release notes — Current Web SDK baseline.
• Firebase Admin Node.js SDK release notes — Current Admin/Firestore dependency baseline.
• Firebase CLI release notes — Current CLI baseline.