Adding documents (add vs set) in Firebase - Trade-offs & Expert Analysis

Overview - Adding documents (add vs set)

What is it?

Adding documents in Firebase Firestore means saving data into the database. You can do this using two main methods: 'add' and 'set'. 'Add' creates a new document with a unique ID automatically, while 'set' writes data to a specific document ID you choose. Both methods store your data but work slightly differently.

Why it matters

This exists to help you save and organize data in your app's database easily. Without clear ways to add documents, managing data would be confusing and error-prone. Choosing between 'add' and 'set' affects how your data is structured and updated, which impacts your app's reliability and user experience.

Where it fits

Before learning this, you should understand basic Firebase Firestore concepts like collections and documents. After this, you can learn about updating, deleting documents, and querying data to build full database interactions.

Mental Model

Core Idea

Adding documents with 'add' automatically creates a new unique document, while 'set' writes data to a chosen document ID, replacing or merging existing data.

Think of it like...

Imagine a filing cabinet: 'add' is like putting a new file in the cabinet with a label the cabinet maker assigns, while 'set' is like placing a file in a specific drawer and folder you pick.

Firestore Collection
  ├─ Document (auto-ID) ← add
  └─ Document (chosen ID) ← set

add: collection.add(data) → new doc with unique ID
set: collection.doc('myID').set(data) → doc with 'myID'

Build-Up - 7 Steps

1

Foundation

Understanding Firestore Collections and Documents

Concept: Learn what collections and documents are in Firestore.

Firestore stores data in collections, which are like folders. Inside collections are documents, which hold your data as key-value pairs. Each document has an ID that identifies it uniquely within the collection.

Result

You know that data is organized in collections and documents, and documents have IDs.

Understanding this basic structure is essential because adding documents means creating or updating these documents inside collections.

2

Foundation

Basics of Adding Data to Firestore

Concept: Learn the simplest way to add data to Firestore.

You can add data by calling 'add' on a collection, which creates a new document with a unique ID automatically. For example: collection.add({name: 'Alice'}) adds a new document with a generated ID.

Result

A new document with your data appears in the collection with a unique ID.

Knowing that 'add' creates documents with unique IDs helps you quickly store data without worrying about naming.

3

Intermediate

Using 'set' to Write Data to Specific Documents

🤔Before reading on: do you think 'set' can create a new document if the ID doesn't exist, or only update existing ones? Commit to your answer.

Concept: 'set' writes data to a document with a specific ID you provide. It can create or overwrite that document.

You use 'set' by specifying the document ID: collection.doc('user123').set({name: 'Bob'}). If 'user123' doesn't exist, Firestore creates it. If it exists, 'set' replaces its data by default.

Result

The document with ID 'user123' now contains the new data, created or replaced.

Understanding that 'set' targets a specific document ID gives you control over your data's location and updates.

4

Intermediate

Difference Between 'add' and 'set' Methods

🤔Before reading on: do you think 'add' allows you to specify the document ID? Commit to your answer.

Concept: 'add' auto-generates document IDs, while 'set' requires you to specify the document ID.

'add' is simple and fast for new documents without caring about IDs. 'set' is for when you want to control or update a document at a known ID. 'add' returns the new document reference with its ID.

Result

'add' creates documents with random IDs; 'set' writes to chosen IDs.

Knowing this difference helps you decide which method fits your app's data organization needs.

5

Intermediate

Merging Data with 'set' to Avoid Overwrites

🤔Before reading on: do you think 'set' always replaces all data, or can it merge with existing data? Commit to your answer.

Concept: 'set' can merge new data with existing document data instead of replacing it.

By passing {merge: true} as an option, 'set' updates only specified fields, keeping others intact. Example: collection.doc('user123').set({age: 30}, {merge: true}) adds or updates 'age' without removing other fields.

Result

Document data is updated partially without losing existing fields.

Understanding merge prevents accidental data loss when updating documents.

6

Advanced

Handling Document IDs and Collisions in Production

🤔Before reading on: do you think using 'add' can cause document ID conflicts? Commit to your answer.

Concept: 'add' avoids ID conflicts by generating unique IDs, while 'set' can cause overwrites if IDs collide.

In production, using 'add' is safer for new data to avoid accidental overwrites. Using 'set' with fixed IDs requires careful ID management to prevent data loss. You can generate your own unique IDs with collection.doc(id) if needed.

Result

You prevent data overwrites and maintain data integrity by choosing the right method.

Knowing how IDs work helps avoid bugs and data corruption in real apps.

7

Expert

Performance and Security Implications of 'add' vs 'set'

🤔Before reading on: do you think 'add' and 'set' have different security or performance impacts? Commit to your answer.

Concept: The choice between 'add' and 'set' affects Firestore security rules and write performance subtly.

'add' always creates new documents, so security rules must allow creation. 'set' can create or overwrite, so rules must handle both. Overwriting large documents with 'set' can be more expensive than merging. Also, predictable IDs with 'set' can simplify security but risk collisions.

Result

You design better security rules and optimize writes by understanding these differences.

Knowing these subtle effects helps build secure, efficient, and maintainable Firestore apps.

Under the Hood

'add' generates a unique document ID using a random 20-character string, ensuring no collisions. It then writes the data under this ID. 'set' targets a document reference by ID; if the document exists, it overwrites or merges data; if not, it creates it. Firestore stores documents as JSON-like objects in a distributed database optimized for fast reads and writes.

Why designed this way?

Firestore was designed for flexible, scalable data storage. 'add' simplifies creating new documents without ID management, reducing developer errors. 'set' gives control when specific document IDs are needed, supporting updates and merges. This dual approach balances ease of use and precision.

Firestore Collection
  │
  ├─ add() ──▶ [Auto-generated ID] ──▶ Document with data
  │
  └─ doc(ID).set() ──▶ [Specified ID] ──▶ Document created or updated

Operations:
  add: generates ID → writes data
  set: uses ID → creates or overwrites or merges data

Myth Busters - 4 Common Misconceptions

Quick: Does 'add' let you specify the document ID? Commit yes or no.

Common Belief: 'add' lets you choose the document ID when adding data.

Reality: 'add' always generates a unique ID automatically; you cannot specify it.

Why it matters: Trying to specify IDs with 'add' leads to confusion and bugs; you must use 'set' for custom IDs.

Quick: Does 'set' always overwrite all data in a document? Commit yes or no.

Common Belief: 'set' always replaces the entire document data, deleting existing fields.

Reality: 'set' can merge new data with existing data if you use the merge option.

Why it matters: Without merge, you risk losing data unintentionally; knowing this prevents data loss.

Quick: Can 'add' cause document ID collisions? Commit yes or no.

Common Belief: 'add' might create documents with duplicate IDs if many writes happen fast.

Reality: 'add' uses a large random ID space to avoid collisions practically entirely.

Why it matters: Understanding this reassures you that 'add' is safe for concurrent writes.

Quick: Does 'set' only update existing documents? Commit yes or no.

Common Belief: 'set' can only update documents that already exist.

Reality: 'set' creates the document if it does not exist.

Why it matters: Knowing this helps you use 'set' for both creating and updating documents.

Expert Zone

1

'add' generates IDs that are lexicographically ordered to optimize Firestore's indexing and performance.

2

Using 'set' with merge:true can cause subtle bugs if nested objects are replaced instead of merged as expected.

3

Firestore security rules can distinguish between create and update operations, so choosing 'add' or 'set' affects rule design.

When NOT to use

'add' is not suitable when you need predictable document IDs or want to update existing documents. Instead, use 'set' with a known ID. Conversely, 'set' is risky if you don't manage IDs carefully, risking overwrites; use 'add' for simple new document creation.

Production Patterns

In production, 'add' is commonly used for user-generated content like posts or messages where unique IDs are fine. 'set' is used for user profiles or settings where document IDs match user IDs, allowing easy updates and lookups.

Connections

Database Transactions

builds-on

Understanding how 'add' and 'set' work helps grasp transactions, which bundle multiple writes atomically, ensuring data consistency.

REST API Methods

similar pattern

'add' is like HTTP POST creating new resources, while 'set' is like PUT replacing or creating a resource at a known URL.

Version Control Systems

opposite pattern

Unlike version control where changes are merged and tracked, 'set' without merge overwrites data, showing different approaches to data updates.

Common Pitfalls

#1 Overwriting entire document unintentionally with 'set' without merge.

Wrong approach:

collection.doc('doc1').set({name: 'Alice'})

Correct approach:

collection.doc('doc1').set({name: 'Alice'}, {merge: true})

Root cause:

Assuming 'set' only updates fields instead of replacing the whole document.

#2 Trying to specify document ID with 'add' method.

Wrong approach:

collection.add({id: 'myID', name: 'Bob'})

Correct approach:

collection.doc('myID').set({name: 'Bob'})

Root cause:

Misunderstanding that 'add' auto-generates IDs and does not accept custom IDs.

#3 Using 'set' with fixed IDs without checking if document exists, causing data loss.

Wrong approach:

collection.doc('user123').set({score: 100})

Correct approach:

collection.doc('user123').set({score: 100}, {merge: true})

Root cause:

Not realizing 'set' replaces entire document by default, deleting other fields.

Key Takeaways

'add' creates new documents with unique IDs automatically, perfect for new data without ID concerns.

'set' writes data to a specific document ID, creating or replacing it, giving you control over document location.

Using 'set' with the merge option updates parts of a document without deleting existing data.

Choosing between 'add' and 'set' affects data structure, update behavior, and security rules in Firestore.

Understanding these methods deeply helps prevent data loss, collisions, and improves app reliability.