Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 31 ยท Firebase Cloud Firestore

Firestore Data Model

Learn how Cloud Firestore stores data: documents, collections, subcollections, field types, references, IDs and size limits, with a runnable stand-in store.

Cloud Firestore is Firebase's main database. It is a document database: instead of tables with rows and columns, you store small JSON-like records called documents, and you group them into collections. There is no schema to declare up front. Two documents in the same collection can have different fields.

The model looks simple, and it is, but it has strict rules about how data nests and how big a record may grow. Because Firestore has no joins, the shape you choose today decides which questions you can ask cheaply tomorrow. This lesson teaches the building blocks and a way of thinking about them. Later lessons cover writes, queries and realtime listeners.

The real Firestore needs a Firebase project and network access, so it cannot run on this site. The SDK code below is read-only. The runnable examples use a small stand-in store that mimics the path rules so you can experiment. It is not Firestore and does not copy its internals.

Documents, collections and paths

Three building blocks

Document A named record of fields, like a JSON object.
Collection A container that holds only documents.
Subcollection A collection that lives inside one document.

Collections hold documents. Documents may hold subcollections.

1 / 2

A document is a set of named fields. A collection is a container of documents; it cannot hold fields or other collections directly. A document may own subcollections, which can nest further.

Every document has a path made of segments separated by slashes. Collections sit at odd positions (1st, 3rd, ...) and documents at even positions (2nd, 4th, ...):

TEXT
users                      collection
users/ada                  document
users/ada/notes            subcollection
users/ada/notes/n1         document

A path that ends on a collection has an odd number of segments, and a path that ends on a document has an even number. The SDK enforces this and throws if you ask for a document using a collection path.

In the web SDK (version 9 and later, the modular one) you create references like this. A reference is just a pointer; creating one reads nothing from the server:

JavaScript
import { getFirestore, doc, collection } from "firebase/firestore";

const db = getFirestore();

const adaRef = doc(db, "users", "ada");              // users/ada
const notesRef = collection(db, "users", "ada", "notes");
const noteRef = doc(db, "users/ada/notes/n1");       // same thing as one string

Two details surprise newcomers. First, a document does not need to "exist" for its subcollection to exist: you can write users/ada/notes/n1 without ever creating users/ada. Second, deleting a document does not delete its subcollections. The notes stay behind, orphaned, until you delete them yourself (usually with a script or a Cloud Function).

Try it: a stand-in store with path rules

This stand-in keeps documents in a Map keyed by their full path. It checks segment counts just like the real SDK, and it lists a collection by finding documents exactly one level below a collection path.

JS A document store with collection paths

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that list("users") returns only ada and linus. The notes are one level deeper, so they belong to a different collection. Firestore queries work the same way: a query on users never returns documents from users/ada/notes.

Field types

A document's fields can hold these types:

Type Notes
String UTF-8 text
Number 64-bit integer or double, stored as separate types
Boolean true or false
Map A nested object, for example address: { city, zip }
Array An ordered list; arrays cannot directly contain other arrays
Null An explicit empty value
Timestamp A point in time with nanosecond precision
Geopoint Latitude and longitude
Bytes Binary data
Reference A pointer to another document

A map is a field that contains named sub-fields. It lives inside the same document, so reading the document reads the map too. You can query a nested value with dot notation, such as address.city.

A reference stores the path of another document. It does not follow itself; you read the target with a second request. Think of it as a foreign key that the database never checks:

JavaScript
import { doc, setDoc } from "firebase/firestore";

await setDoc(doc(db, "orders", "o-1001"), {
  customer: doc(db, "users", "ada"),   // reference field
  total: 42.5,
  paidAt: new Date("2026-03-01T10:00:00Z"),  // stored as a Timestamp
  tags: ["gift", "express"],
  shipping: { city: "Lisbon", country: "PT" },
});

The reference to users/ada will keep pointing there even if that document is later deleted. Nothing in Firestore prevents a dangling reference.

Document IDs

Every document has an ID that is unique inside its collection. You choose it, or let Firestore generate a 20-character random one with addDoc or doc(collection(...)). Rules for IDs:

  • They cannot contain a forward slash /.
  • They cannot be . or .., and cannot match the pattern __name__ (two underscores on each side).
  • They must be valid UTF-8 and at most 1,500 bytes.

Pick an ID yourself when the data has a natural unique key that you will use to look it up, such as a user's auth UID (users/<uid>). Let Firestore generate one when you just need a new record. Avoid IDs that increase steadily, like 1, 2, 3 or a bare timestamp, for very write-heavy collections: Firestore spreads random IDs evenly across its servers, and monotonically increasing ones can create a hot spot.

Limits that shape your design

You do not need to memorise every limit, but these three change how you design:

  1. A document is at most 1 MiB. That includes field names and values. Do not store an ever-growing list inside one document.
  2. Sustained writes to a single document are limited to roughly one per second. A busy counter or chat log stored in one document will hit this. Spread the data across documents.
  3. A document is always read whole. There is no way to fetch half a document in the client SDK, so a huge document makes every small read expensive.

Designing around queries

Relational design starts with entities and normalises. Firestore design starts with screens and queries: list what each screen must show, then shape the data so one read answers it.

Compare two ways to store comments on a blog post. Embedding them inside the post is easy at first, but grows without bound. A subcollection keeps the post small and lets you page through comments:

TEXT
posts/p1             { title, authorName, commentCount }
posts/p1/comments/c1 { author, text, createdAt }
posts/p1/comments/c2 { author, text, createdAt }

Notice authorName is copied into the post even though it also lives in users. Copying a small, rarely changing value so you can render a screen with one read is called denormalization. You will use it a lot, and the queries lesson explains the cost.

JS Why unbounded arrays break the 1 MiB limit

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The embedded design stops working after a few thousand comments, no matter how small each one is. The subcollection design has no such ceiling, and you can read ten comments at a time instead of all of them.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which path points at a document?

    Document paths have an even number of segments. users/ada/notes/n1 has four. The other two end on collections.
  2. 2. You delete the document users/ada. What happens to users/ada/notes/n1?

    Deleting a document never deletes its subcollections. They remain until you remove them explicitly.
  3. 3. Why is storing every chat message in one array field a bad idea?

    The array keeps growing toward the size limit, and every read downloads all of it. A subcollection avoids both problems.
  4. 4. What does a reference field guarantee?

    A reference holds a path. Firestore does not check it or follow it, so you read the target yourself and handle missing documents.

Summary

  • Firestore stores documents (field maps) inside collections; documents may own subcollections.
  • Paths alternate collection, document, collection, document; segment count tells you which one a path is.
  • Field types include maps, arrays, timestamps, geopoints and references; references are unchecked pointers.
  • IDs are yours or auto-generated (20 characters); they cannot contain /.
  • A document is limited to 1 MiB and read whole, so use subcollections for growing lists.
  • Design from your screens and queries, and denormalize small values deliberately.

Next: Reading and Writing Documents.