Firestore document model in GCP - Deep Dive

Overview - Firestore document model

What is it?

Firestore is a cloud database that stores data as documents. Each document holds data as key-value pairs, like a small record or a form. Documents are grouped into collections, which help organize data. This model makes it easy to find, update, and manage data in apps.

Why it matters

Without a clear document model, storing and retrieving data would be slow and confusing, especially for apps that need to work fast and scale. Firestore's document model solves this by organizing data in simple, flexible units that apps can quickly access and update. This helps apps stay responsive and reliable, even with many users.

Where it fits

Before learning Firestore's document model, you should understand basic database concepts like tables and records. After this, you can learn about Firestore queries, security rules, and how to design scalable data structures for apps.

Mental Model

Core Idea

Firestore stores data as small, flexible documents grouped in collections, making data easy to organize and access.

Think of it like...

Imagine a filing cabinet where each folder is a collection, and inside each folder are sheets of paper (documents) with information written as labeled notes (key-value pairs). You can quickly find and update any sheet without sorting through everything.

Firestore Database
┌─────────────────────────────┐
│         Collection          │
│  ┌───────────────┐          │
│  │   Document    │          │
│  │ ┌───────────┐ │          │
│  │ │ key: value│ │          │
│  │ │ key: value│ │          │
│  │ └───────────┘ │          │
│  └───────────────┘          │
│  ┌───────────────┐          │
│  │   Document    │          │
│  │   ...         │          │
│  └───────────────┘          │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Documents and Fields

Concept: Firestore stores data in documents, which are like small records made of fields with key-value pairs.

A document is a container for data. Each document has fields, where each field has a name (key) and a value. Values can be simple like text or numbers, or complex like lists or nested objects. Documents are identified by unique IDs.

Result

You can store structured data in small, manageable units called documents.

Understanding that documents hold data as key-value pairs helps you see how Firestore organizes information flexibly and simply.

2

Foundation

Collections Group Documents

Concept: Documents are grouped into collections, which act like folders organizing related documents.

A collection is a container for documents. You cannot store data directly in a collection, only documents. Collections help organize data by grouping similar documents together, like all users or all orders.

Result

Data is organized hierarchically: collections contain documents, making it easy to find related data.

Knowing collections group documents helps you design your data layout for easy access and management.

3

Intermediate

Nested Data with Subcollections

🤔Before reading on: do you think documents can contain other documents directly? Commit to your answer.

Concept: Documents can have subcollections, which are collections nested inside a document, allowing deeper data organization.

Firestore allows collections inside documents, called subcollections. This means a document can have its own collections, which then contain more documents. This helps model complex relationships, like a user document having a subcollection of their orders.

Result

You can build multi-level data structures that reflect real-world relationships.

Understanding subcollections lets you model complex data naturally without flattening everything into one big collection.

4

Intermediate

Data Types and Flexibility

🤔Before reading on: do you think all fields in Firestore must have the same data type? Commit to your answer.

Concept: Firestore supports many data types for fields, including strings, numbers, booleans, arrays, maps, and timestamps.

Fields in documents can hold different types of data. For example, a field can be a simple string like a name, a number like age, a boolean like true/false, an array of values, or a map (nested object) with its own key-value pairs. This flexibility helps store varied data easily.

Result

You can store rich, varied data in documents without rigid schemas.

Knowing Firestore supports many data types helps you design documents that fit your app's needs without extra complexity.

5

Intermediate

Document IDs and References

🤔Before reading on: do you think document IDs must be human-readable or can they be random? Commit to your answer.

Concept: Each document has a unique ID, which can be set by you or auto-generated, and documents can reference others by their paths.

Documents are identified by IDs within their collection. You can choose meaningful IDs or let Firestore create random ones. Documents can also store references to other documents, which are like links pointing to data elsewhere in the database.

Result

You can uniquely identify and link documents, enabling relationships and easy retrieval.

Understanding document IDs and references helps you connect data pieces and navigate your database efficiently.

6

Advanced

Designing for Scalability and Performance

🤔Before reading on: do you think deeply nested documents always improve performance? Commit to your answer.

Concept: How you structure documents and collections affects app speed and cost; shallow, well-planned layouts often perform better.

Firestore charges and limits depend on document reads and writes. Deep nesting can cause many small reads, slowing apps and increasing cost. Designing flatter structures or using subcollections wisely helps balance data organization with performance. Also, avoid very large documents to keep reads fast.

Result

Your app stays fast and cost-effective as it grows.

Knowing how document structure impacts performance helps you build apps that scale smoothly without surprises.

7

Expert

Consistency and Atomicity in Document Updates

🤔Before reading on: do you think Firestore can update multiple documents atomically in one operation? Commit to your answer.

Concept: Firestore provides atomic operations on single documents and transactions for multiple documents, ensuring data stays consistent.

Updates to a single document are atomic, meaning they fully succeed or fail together. For multiple documents, Firestore offers transactions and batch writes to apply changes atomically. This prevents partial updates that could corrupt data. Understanding this helps design reliable data flows.

Result

Your app maintains correct data even with concurrent users and complex updates.

Knowing Firestore's atomicity limits guides you to use transactions properly, avoiding subtle bugs in multi-document updates.

Under the Hood

Firestore stores each document as a separate entity in a distributed database. When you read or write a document, Firestore accesses only that document's data, not the whole collection. This is possible because documents are independent units with unique IDs. Subcollections are stored as separate collections linked by document paths. Firestore uses indexes to quickly find documents based on queries.

Why designed this way?

Firestore was designed for scalability and real-time apps. Storing data as independent documents allows fast, targeted reads and writes without loading unnecessary data. The hierarchical model with collections and subcollections reflects natural data relationships and supports flexible app needs. Alternatives like relational tables were less suited for mobile and web apps needing quick sync and offline support.

Firestore Storage Model
┌───────────────────────────────┐
│         Collection A           │
│  ┌───────────────┐            │
│  │   Document 1  │            │
│  │  (stored as   │            │
│  │  separate     │            │
│  │  entity)      │            │
│  └───────────────┘            │
│       │                       │
│       ▼                       │
│  Subcollection B              │
│  ┌───────────────┐            │
│  │   Document 2  │            │
│  │  (separate)   │            │
│  └───────────────┘            │
└───────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think Firestore documents can be larger than 1 MB? Commit to yes or no.

Common Belief: Firestore documents can be as large as you want, so you can store big files or lots of data in one document.

Reality: Firestore documents have a size limit of 1 MB, so large files or huge data must be split or stored elsewhere.

Why it matters: Ignoring this limit can cause errors or slow app performance when documents exceed size, leading to failed writes or slow reads.

Quick: Do you think Firestore collections can contain other collections directly? Commit to yes or no.

Common Belief: Collections can contain other collections directly, like folders inside folders.

Reality: Collections cannot contain collections directly; only documents can have subcollections.

Why it matters: Misunderstanding this leads to wrong data models that don't work and cause confusion when accessing data.

Quick: Do you think Firestore queries can join data from multiple collections like SQL? Commit to yes or no.

Common Belief: Firestore supports joins across collections like traditional SQL databases.

Reality: Firestore does not support joins; you must design data to avoid joins or perform multiple queries in your app.

Why it matters: Expecting joins can cause inefficient queries or complex app logic, hurting performance and maintainability.

Quick: Do you think Firestore transactions can update unlimited documents atomically? Commit to yes or no.

Common Belief: Firestore transactions can update any number of documents atomically without limits.

Reality: Firestore transactions have limits on size and number of documents; very large transactions can fail or be slow.

Why it matters: Not knowing this can cause unexpected failures in complex updates, risking data inconsistency.

Expert Zone

1

Firestore indexes every field by default, but complex queries may require custom composite indexes to work efficiently.

2

Subcollections are independent; security rules and queries apply separately, allowing fine-grained access control.

3

Document references store paths, not copies of data, so changes in referenced documents reflect immediately without duplication.

When NOT to use

Firestore document model is not ideal for complex relational data requiring many joins or multi-table transactions; in such cases, a relational database like Cloud SQL is better. Also, for very large binary files, use Cloud Storage instead of documents.

Production Patterns

In production, developers often denormalize data by duplicating some fields across documents to avoid expensive queries. They use subcollections to model one-to-many relationships and batch writes to update multiple documents efficiently. Security rules are carefully designed per collection and document level to protect data.

Connections

Relational Database Tables

Firestore documents are like rows in tables, but more flexible and nested.

Understanding tables helps grasp documents as records, but Firestore allows nested data unlike flat tables.

JSON Data Format

Firestore documents store data similarly to JSON objects with key-value pairs.

Knowing JSON helps understand how Firestore fields can hold nested objects and arrays naturally.

Library Cataloging Systems

Like organizing books into sections and shelves, Firestore organizes data into collections and documents.

Seeing Firestore as a catalog system clarifies how data is grouped and accessed efficiently.

Common Pitfalls

#1 Trying to store large files directly in documents.

Wrong approach:

document.set({ fileData: largeBinaryData })

Correct approach:

Upload large files to Cloud Storage and store the file URL in the document.

Root cause:

Misunderstanding document size limits and storage purpose.

#2 Designing deeply nested data without subcollections.

Wrong approach:

Storing all related data in one large document with many nested fields.

Correct approach:

Use subcollections to split related data into separate documents for better performance.

Root cause:

Not knowing subcollections exist or how they improve scalability.

#3 Expecting Firestore to perform SQL-style joins.

Wrong approach:

Querying multiple collections expecting automatic joins.

Correct approach:

Perform multiple queries in the app and combine results manually or denormalize data.

Root cause:

Assuming Firestore works like relational databases.

Key Takeaways

Firestore organizes data as documents with key-value pairs inside collections, making data flexible and easy to manage.

Documents have size limits and support many data types, including nested objects and arrays.

Subcollections allow hierarchical data modeling, enabling complex relationships without flattening data.

Designing data structure affects app performance and cost; flatter structures and careful use of subcollections help scalability.

Firestore supports atomic updates on single documents and transactions for multiple documents, but has limits to consider.