Document / Collection Hierarchy, Paths, IDs, Subcollections, and the Absence of Traditional Server-Side Joins in Core Operations

Learning outcomes

AtlasMart now has a safe emulator environment, but its data model is still only a pair of toy product documents. The next design mistake would be to treat Firestore collections as SQL tables, references as foreign keys, and subcollections as automatic child rows. Firestore gives you a hierarchy of addressable documents and typed fields; the application must still decide which facts live together, which paths express ownership, and which reads can be satisfied without a server-side join.

1. Firestore paths alternate collection and document segments

Cloud Firestore stores documents inside collections. A collection is a container for documents; it does not directly hold raw fields. A document is the storage unit that owns fields. Paths therefore alternate: collection/document/collection/document. AtlasMart can address products/p-1001 or a nested review at products/p-1001/reviews/r-001, but products/p-1001/reviews names a collection, not a document, and products/products/p-1001 is a different path entirely.

Collections are implicit. You do not provision an empty collection object first: writing the first document makes the collection visible, and removing all its documents removes the collection from normal data views. Document IDs are unique only within their immediate collection. The same ID r-001 can exist under many different product review subcollections without collision because the full paths differ.

2. Subcollections are independent storage, not embedded children

A subcollection is convenient when child data grows independently of the parent. Reviews can grow without making the product document approach its size limit, and queries can target one review collection or later use a collection-group query across every reviews subcollection. The tradeoff is lifecycle complexity: deleting products/p-1001 does not automatically delete products/p-1001/reviews/*.

A subtle but important boundary is that a subcollection document can exist even if the parent document has no stored fields. The path products/p-ghost/reviews/r-1 can exist while products/p-ghost itself does not. The console can visually surface such non-existent parents, but ordinary document reads/queries still distinguish the missing parent from a real stored document. Therefore, "the path contains a product ID" is not proof that the product document exists.

3. Document references are typed values, not joins

Firestore can store a DocumentReference value such as a reference from an order line to products/p-1001. That value preserves the target path as a Firestore-native type. It does not cause the target document to be fetched when the order is read, it does not enforce that the target exists, and deleting the target does not rewrite or null out stored references.

With Native Core operations, the application normally performs another read when it needs the referenced document, or it duplicates the read-critical fields it needs inside the source document. That is why references must be evaluated against read count, latency, offline behavior, consistency requirements, and security rules—not against the intuition that they behave like SQL foreign keys. Enterprise Pipeline operations add different query capabilities and later chapters will cover them; Chapter 02 must not back-port those capabilities into Standard Core semantics.

4. AtlasMart hierarchy: make ownership and query surfaces visible

For Chapter 02, AtlasMart will keep product catalog documents at the root because many screens query products independently of a user. Reviews belong under a product path for local ownership examples, while orders live at a root collection because operational services often need cross-user order workflows. The order stores a stable userId and selected snapshot fields instead of assuming a join to a profile at read time.

products/p-1001  name: "Trail Camera"  category: "cameras"  sellerId: "s-001"  description: "..."  attributes: { resolution: "4K", weatherproof: true }products/p-1001/reviews/r-001  userId: "u-1001"  rating: 5  body: "Works well in rain"users/u-1001  displayName: "A. Shopper"  preferredCurrency: "USD"orders/o-9001  userId: "u-1001"  status: "placed"  itemSnapshots: [{ productId: "p-1001", name: "Trail Camera", unitPrice: 129.90 }]

The duplicated product name and unit price in the order are not accidental corruption: they can be a historical snapshot of what was purchased. Whether that is the right model is an access-pattern decision. Chapter 03 will compare embedding, references, duplication, and fan-out systematically.

5. Hands-on lab: seed exact paths and prove what exists

Continue the Chapter 01 project. The Admin SDK writes deterministic fixtures because the server path is trusted and bypasses client Security Rules. The script then reads the parent product, nested review, and a deliberately missing parent to show that path syntax and document existence are separate facts.

process.env.FIRESTORE_EMULATOR_HOST = "127.0.0.1:8080";process.env.GCLOUD_PROJECT = "demo-atlasmart-firestore";import { initializeApp } from "firebase-admin/app";import { getFirestore, Timestamp } from "firebase-admin/firestore";initializeApp({ projectId: "demo-atlasmart-firestore" });const db = getFirestore();await db.doc("products/p-1001").set({  name: "Trail Camera",  category: "cameras",  sellerId: "s-001",  schemaVersion: 2,  updatedAt: Timestamp.fromDate(new Date("2026-09-14T09:00:00Z"))}, { merge: true });await db.doc("products/p-1001/reviews/r-001").set({  userId: "u-1001",  rating: 5,  body: "Works well in rain",  schemaVersion: 1});// Deliberately create a child below a parent document that has no fields.await db.doc("products/p-ghost/reviews/r-orphan-demo").set({  userId: "u-1002", rating: 3, schemaVersion: 1});for (const path of [  "products/p-1001",  "products/p-1001/reviews/r-001",  "products/p-ghost",  "products/p-ghost/reviews/r-orphan-demo"]) {  const snap = await db.doc(path).get();  console.log(path, { exists: snap.exists, data: snap.exists ? snap.data() : null });}

Expected invariant: products/p-1001, its review, and the orphan-demo review exist; products/p-ghost itself does not. Inspect the same paths in the Emulator UI. That visual inspection is supporting evidence, not a substitute for the programmatic exists assertions.

process.env.FIRESTORE_EMULATOR_HOST = "127.0.0.1:8080";process.env.GCLOUD_PROJECT = "demo-atlasmart-firestore";// Use Admin SDK deletes only for the exact fixture paths created above.// Do not translate this into an unscoped production recursive delete.

6. Deliberately wrong approach: build a relational graph out of references

Suppose every order stores only a product reference, every product stores only a seller reference, and the UI expects one query to return order + product + seller. The model looks normalized, but Core operations have no traditional server-side join to materialize that graph. A mobile client now performs a chain of network reads, offline screens become harder to reason about, read cost increases, and Security Rules must authorize each path separately.

The repair is not “never use references.” It is to name the screen/query contract first. If the order receipt must show the purchased name and price forever, copy those immutable snapshot values into the order. If a seller profile is optional and changes independently, a reference plus an explicit read may be appropriate. If the target must exist, enforce that invariant in a trusted transaction/workflow rather than assuming the reference type does it for you.

Knowledge check

Summary and next step

Firestore gives AtlasMart addressable documents in alternating collection/document paths, not relational tables with foreign keys. Subcollections scale child lists but create lifecycle obligations; references are typed paths rather than joins. With that hierarchy explicit, the next lesson can focus on what values actually live inside a document and how their types sort, serialize, and cross SDK boundaries.

Next: Supported Native Data Types, Null, Numeric Ordering, Timestamps, References, GeoPoints, Bytes, Arrays, and Maps.

Authoritative references

• Cloud Firestore data model — Official document/collection hierarchy and subcollection model.
• Choose a data structure — Official guidance for nested data, subcollections, and root-level collections.
• Supported data types — Current Native data types, sort ordering, precision, and edition-specific value behavior.
• Usage and limits — Current document, field, path, nesting, index-entry, and request limits.
• Index types in Cloud Firestore — Automatic/manual indexing, map/array indexing, index entries, and exemptions.
• Best practices for Cloud Firestore — Official document-ID, hotspot, location, and index-fan-out guidance.
• Add data to Cloud Firestore — Current SDK examples for IDs, timestamps, nested fields, and custom object conversion.
• Firebase release notes — Current Firebase SDK and CLI version baseline.
• Connect to the Firestore Emulator — Local emulator connection and production-difference guidance.