Setting with merge option in Firebase - Deep Dive

Overview - Setting with merge option

What is it?

Setting with merge option in Firebase means updating parts of a document without replacing the whole document. Instead of overwriting all data, it combines new data with existing data. This helps keep unchanged data safe while adding or changing only specific fields. It is useful when you want to update some details but keep the rest intact.

Why it matters

Without the merge option, updating a document would erase all existing data not included in the update. This could cause accidental data loss and require extra work to restore missing information. The merge option solves this by allowing safe, partial updates, making apps more reliable and easier to maintain.

Where it fits

Before learning this, you should understand basic Firebase Firestore document structure and how to set or update documents. After this, you can explore advanced Firestore features like transactions, batched writes, and security rules that control data access.

Mental Model

Core Idea

Setting with merge option updates only specified fields in a document, keeping all other fields unchanged.

Think of it like...

Imagine writing a letter and wanting to change just one sentence without rewriting the whole page. Using the merge option is like crossing out and rewriting only that sentence, leaving the rest of the letter untouched.

Document {
  ├─ field1: value1
  ├─ field2: value2
  ├─ field3: value3
}

Update with merge {
  └─ field2: newValue
}

Resulting Document {
  ├─ field1: value1
  ├─ field2: newValue
  ├─ field3: value3
}

Build-Up - 6 Steps

1

Foundation

Understanding Firestore Documents

Concept: Firestore stores data in documents, which are like records with fields and values.

A Firestore document is a set of key-value pairs, like a small JSON object. Each document lives in a collection. For example, a user document might have fields like name, age, and email.

Result

You can read and write whole documents in Firestore.

Knowing that documents hold data as fields helps you understand what happens when you update or replace them.

2

Foundation

Basic Document Set Operation

Concept: Setting a document without merge replaces the entire document with new data.

When you use set() without merge, Firestore deletes all existing fields and writes only the new ones you provide. For example, setting {age: 30} on a document that had {name: 'Anna', age: 25} will remove the name field.

Result

The document now only has the age field with value 30.

Understanding that set() without merge overwrites everything prevents accidental data loss.

3

Intermediate

Using Merge Option to Update Fields

🤔Before reading on: do you think set() with merge updates only given fields or replaces the whole document? Commit to your answer.

Concept: The merge option tells Firestore to update only specified fields, keeping others intact.

Using set(data, {merge: true}) updates the fields in data but leaves other fields unchanged. For example, set({age: 30}, {merge: true}) on {name: 'Anna', age: 25} changes age to 30 but keeps name.

Result

The document now has {name: 'Anna', age: 30}.

Knowing merge updates only parts of a document helps you safely change data without losing unrelated fields.

4

Intermediate

Difference Between Update and Set with Merge

🤔Before reading on: do you think update() and set() with merge behave the same? Commit to your answer.

Concept: update() changes existing fields and fails if the document doesn't exist; set() with merge creates or updates safely.

update() modifies only specified fields but throws an error if the document is missing. set() with merge creates the document if missing and updates fields if present.

Result

set() with merge is safer for unknown document existence; update() is stricter.

Understanding this difference helps choose the right method for your app's needs.

5

Advanced

Nested Field Merging with Dot Notation

🤔Before reading on: do you think merge updates nested fields replace the whole nested object or just parts? Commit to your answer.

Concept: Merge can update nested fields inside objects without replacing the entire nested object.

Using dot notation like set({'address.city': 'New York'}, {merge: true}) updates only the city inside the address object, keeping other address fields unchanged.

Result

Only the city field inside address changes; other address fields stay the same.

Knowing how to update nested fields precisely avoids overwriting complex data structures.

6

Expert

Merge Behavior with Arrays and Server Timestamps

🤔Before reading on: does merge replace arrays entirely or merge their contents? Commit to your answer.

Concept: Merge replaces arrays entirely; it does not merge array contents. Server timestamps update correctly with merge.

When merging, arrays are replaced, not merged element-wise. Using FieldValue.serverTimestamp() with merge updates the timestamp field without affecting others.

Result

Arrays are fully replaced; timestamps update safely with merge.

Understanding array replacement prevents unexpected data loss; knowing timestamp behavior helps with accurate time tracking.

Under the Hood

Firestore stores documents as key-value maps. When set() with merge is called, Firestore reads the existing document, combines the new fields with existing ones, and writes back the combined map. It uses dot notation to target nested fields. Arrays are treated as whole values and replaced entirely. Server timestamps are special sentinel values that Firestore replaces with the current time during write.

Why designed this way?

Firestore was designed for flexible, scalable cloud data storage. The merge option allows partial updates to avoid costly full document rewrites and accidental data loss. Arrays are replaced fully because merging arrays element-wise is complex and ambiguous. Server timestamps are handled specially to ensure consistent time values across clients.

Client Request
   │
   ▼
Firestore Backend
   │
   ├─ Reads existing document
   │
   ├─ Merges new fields with existing fields
   │    ├─ Uses dot notation for nested fields
   │    ├─ Replaces arrays fully
   │    └─ Processes server timestamp sentinels
   │
   └─ Writes updated document back
   │
   ▼
Document Updated

Myth Busters - 4 Common Misconceptions

Quick: Does set() with merge update only specified fields or replace the whole document? Commit to your answer.

Common Belief: set() always replaces the entire document, even with merge option.

Reality: set() with merge updates only specified fields, keeping others intact.

Why it matters: Believing this causes developers to avoid merge and risk overwriting data unintentionally.

Quick: Does merge combine arrays element-wise or replace them? Commit to your answer.

Common Belief: Merge option merges arrays by combining their elements.

Reality: Merge replaces arrays entirely; it does not merge their contents.

Why it matters: Assuming arrays merge can lead to unexpected data loss or incorrect data.

Quick: Can update() create a new document if it doesn't exist? Commit to your answer.

Common Belief: update() creates a document if missing, like set() with merge.

Reality: update() fails if the document does not exist; it only modifies existing documents.

Why it matters: Misusing update() can cause runtime errors and failed writes.

Quick: Does set() with merge update nested fields replace the whole nested object? Commit to your answer.

Common Belief: Merging nested fields replaces the entire nested object.

Reality: Merging nested fields updates only specified nested fields, leaving others intact.

Why it matters: Misunderstanding this can cause accidental overwriting of nested data.

Expert Zone

1

Merge does not merge arrays element-wise; arrays are replaced fully, which can surprise developers expecting partial array updates.

2

Using set() with merge is safer for unknown document existence because it creates or updates, unlike update() which requires the document to exist.

3

Server timestamp fields with FieldValue.serverTimestamp() work seamlessly with merge, allowing precise time updates without affecting other fields.

When NOT to use

Avoid using set() with merge when you want to replace the entire document intentionally or when you need atomic multi-document transactions. In those cases, use update() for existing documents or batch writes and transactions for atomicity.

Production Patterns

In production, set() with merge is commonly used for user profile updates where only some fields change. It is also used in form submissions to update partial data safely. Developers combine merge with security rules to protect sensitive fields from unintended overwrites.

Connections

Database Transactions

Builds-on

Understanding merge helps grasp how partial updates work, which is essential before learning transactions that ensure multiple updates happen safely together.

Version Control Systems

Similar pattern

Merge in Firestore is like merging code changes in version control, where only differences are combined, not the entire file replaced.

Editing a Shared Document

Analogous process

Partial updates with merge resemble multiple people editing different parts of a shared document without overwriting each other's changes.

Common Pitfalls

#1 Overwriting entire document unintentionally

Wrong approach:

db.collection('users').doc('user1').set({age: 30});

Correct approach:

db.collection('users').doc('user1').set({age: 30}, {merge: true});

Root cause:

Not using merge option causes full document replacement, losing other fields.

#2 Expecting update() to create new documents

Wrong approach:

db.collection('users').doc('user2').update({age: 25});

Correct approach:

db.collection('users').doc('user2').set({age: 25}, {merge: true});

Root cause:

update() fails if document doesn't exist; set() with merge creates or updates.

#3 Trying to merge arrays expecting element-wise update

Wrong approach:

db.collection('users').doc('user1').set({tags: ['new']}, {merge: true}); // expecting tags to add 'new'

Correct approach:

db.collection('users').doc('user1').update({tags: FieldValue.arrayUnion('new')});

Root cause:

Merge replaces arrays fully; to add elements use arrayUnion.

Key Takeaways

Setting with merge option updates only specified fields in a Firestore document, preserving all other data.

Without merge, set() replaces the entire document, which can cause data loss.

Merge works with nested fields using dot notation, allowing precise partial updates.

Arrays are replaced entirely when merged; use special array operations to modify arrays safely.

Choosing between update() and set() with merge depends on whether the document exists and if creation is needed.