Upsert behavior (update or insert) in MongoDB - Step-by-Step Execution

Concept Flow - Upsert behavior (update or insert)

Receive upsert request

↓

Search for document matching filter

↓

Found?

Yes→Update document

↓

Insert new document

↓

Return result

The database checks if a document matches the filter. If yes, it updates it; if no, it inserts a new document.

Execution Sample

MongoDB

db.collection.updateOne(
  { name: "Alice" },
  { $set: { age: 30 } },
  { upsert: true }
)

This command updates Alice's age to 30 if she exists; otherwise, it inserts a new document with name Alice and age 30.

Execution Table

Step	Action	Filter Search Result	Update or Insert	Result
1	Search for document with {name: 'Alice'}	No document found	Insert new document {name: 'Alice', age: 30}	Document inserted
2	Return operation result	-	-	Upsert completed with insert

💡 No matching document found, so a new document was inserted.

Variable Tracker

Variable	Start	After Step 1	After Step 2
Document in collection	[{name: 'Bob', age: 25}]	[{name: 'Bob', age: 25}, {name: 'Alice', age: 30}]	[{name: 'Bob', age: 25}, {name: 'Alice', age: 30}]

Key Moments - 2 Insights

Why does the database insert a new document instead of updating?

Because the filter {name: 'Alice'} did not find any existing document (see execution_table step 1), so upsert inserts a new one.

What happens if a matching document is found?

The database updates the existing document with the new values instead of inserting (not shown in this trace but implied by the flow).

Visual Quiz - 3 Questions

Look at the execution table, what is the filter search result at step 1?

A No document found

B Error occurred

C Document found

D Multiple documents found

💡 Hint

Check the 'Filter Search Result' column in execution_table row 1.

At which step does the database insert a new document?

A Step 2

B Step 1

C No insertion happens

D After step 2

💡 Hint

Look at the 'Update or Insert' column in execution_table row 1.

If the collection already had a document with name 'Alice', what would change in the execution table?

A Filter search result would be 'No document found' and insert happens

B No change, insert always happens

C Filter search result would be 'Document found' and update happens

D Operation would fail

💡 Hint

Refer to the concept_flow where update happens if document is found.

Concept Snapshot

Upsert in MongoDB:
Use updateOne() with upsert:true option.
If filter matches a document, update it.
If no match, insert new document.
Prevents duplicate inserts and ensures data is updated or created.

Full Transcript

Upsert behavior in MongoDB means the database tries to find a document matching the filter. If it finds one, it updates that document with the new data. If it does not find any matching document, it inserts a new document with the given data. This is done using updateOne() or updateMany() with the option upsert:true. The execution flow starts by searching for the document. If found, it updates; if not, it inserts. This prevents duplicates and ensures data is either updated or created as needed.