Upsert behavior (update or insert) in MongoDB

Introduction

Upsert lets you update a record if it exists or add it if it doesn't. This saves time by doing both in one step.

When you want to add a new user or update their info if they already exist.

When syncing data from another system and you want to avoid duplicates.

When saving settings that might be new or changed.

When logging events and you want to update counts or create new entries.

Syntax

MongoDB

db.collection.updateOne(
  <filter>,
  <update>,
  { upsert: true }
)

filter finds the document to update.

update describes the changes to make.

upsert: true means insert if no match is found.

Examples

Update Alice's age to 30 or add Alice if she doesn't exist.

MongoDB

db.users.updateOne(
  { username: "alice" },
  { $set: { age: 30 } },
  { upsert: true }
)

Increase stock by 10 for product 12345 or add it if missing.

MongoDB

db.products.updateOne(
  { sku: "12345" },
  { $inc: { stock: 10 } },
  { upsert: true }
)

Sample Program

This code updates Bob's email if he exists or adds a new user Bob with that email. Then it shows Bob's record.

MongoDB

use testdb

// Try to update a user named 'bob' or insert if not found
 db.users.updateOne(
   { username: "bob" },
   { $set: { email: "[e-mail]" } },
   { upsert: true }
 )

// Find and show the user 'bob'
 db.users.find({ username: "bob" }).toArray()

Important Notes

If multiple documents match the filter, only one is updated.

Without upsert: true, no new document is created.

Use $set to change fields without replacing the whole document.

Summary

Upsert updates a document if found or inserts it if missing.

Use updateOne or updateMany with upsert: true.

This helps keep data consistent with fewer commands.

Practice

1. What does the upsert option do in a MongoDB updateOne operation?

easy

A. It only inserts a new document without updating existing ones.

B. It updates a document if it exists, or inserts a new one if it does not.

C. It deletes a document if it exists, otherwise does nothing.

D. It duplicates the document regardless of existence.

Solution

1. Step 1: Understand the upsert option

   The upsert option in MongoDB means update if found, insert if not found.

2. Step 2: Apply to updateOne operation

   When using updateOne with upsert: true, MongoDB updates the matching document or inserts a new one if none matches.

3. Final Answer:

   It updates a document if it exists, or inserts a new one if it does not. -> Option B

4. Quick Check:

   Upsert = update or insert [OK]

Hint: Upsert means update if found, else insert new [OK]

Common Mistakes:

• Thinking upsert only inserts without updating
• Confusing upsert with delete operation
• Assuming upsert duplicates documents

2. Which of the following is the correct syntax to perform an upsert using updateOne in MongoDB?

easy

A. db.collection.updateOne(filter, update, {update: true})

B. db.collection.updateOne(filter, update, {insert: true})

C. db.collection.updateOne(filter, update, {upsert: true})

D. db.collection.updateOne(filter, update, {replace: true})

Solution

1. Step 1: Recall the updateOne method parameters

   The updateOne method takes a filter, an update document, and an options object.

2. Step 2: Identify the correct option for upsert

   The option to enable upsert is {upsert: true}, which tells MongoDB to insert if no match is found.

3. Final Answer:

   db.collection.updateOne(filter, update, {upsert: true}) -> Option C

4. Quick Check:

   Use upsert: true in options [OK]

Hint: Use {upsert: true} in updateOne options [OK]

Common Mistakes:

• Using {insert: true} instead of {upsert: true}
• Omitting the options object entirely
• Confusing update with replace option

3. Given the collection users with documents:
{ _id: 1, name: "Alice", age: 25 }
What will be the result after running:

db.users.updateOne({ _id: 2 }, { $set: { name: "Bob", age: 30 } }, { upsert: true })

and then querying db.users.find().toArray()?

medium

A. [{ _id: 1, name: "Alice", age: 25 }, { _id: 2, name: "Bob", age: 30 }]

B. [{ _id: 1, name: "Alice", age: 25 }]

C. [{ _id: 2, name: "Bob", age: 30 }]

D. []

Solution

1. Step 1: Understand the updateOne with upsert

   The filter looks for _id: 2, which does not exist, so upsert inserts a new document with _id: 2 and the given fields.

2. Step 2: Check existing documents

   The original document with _id: 1 remains unchanged, so the collection now has two documents.

3. Final Answer:

   [{ _id: 1, name: "Alice", age: 25 }, { _id: 2, name: "Bob", age: 30 }] -> Option A

4. Quick Check:

   Upsert inserts missing document, keeps existing [OK]

Hint: Upsert inserts new if filter misses existing docs [OK]

Common Mistakes:

• Assuming existing documents get deleted
• Thinking upsert only updates existing documents
• Expecting only the new document after upsert

4. You run the following code but it does not insert a new document when no match is found:

db.products.updateOne({ sku: "123" }, { price: 19.99 })

What is the likely error?

medium

A. The filter syntax is incorrect and causes a syntax error.

B. MongoDB does not support upsert with updateOne.

C. The update document is missing the $set operator.

D. Missing the upsert: true option in the updateOne call.

Solution

1. Step 1: Check the updateOne parameters

   The updateOne call lacks the options object with upsert: true, so it only updates existing documents.

2. Step 2: Confirm upsert behavior

   Without upsert: true, no new document is inserted if the filter finds no match.

3. Final Answer:

   Missing the upsert: true option in the updateOne call. -> Option D

4. Quick Check:

   Upsert option needed to insert new docs [OK]

Hint: Add {upsert: true} to updateOne options to insert [OK]

Common Mistakes:

• Forgetting to add upsert option
• Confusing missing $set with upsert behavior
• Believing updateOne cannot upsert

5. You want to update the status field to "active" for a user with email: "[e-mail]". If no such user exists, insert a new document with email and status. Which MongoDB command correctly achieves this?

hard

A. db.users.updateOne({ email: "[e-mail]" }, { $set: { status: "active" } }, { upsert: true })

B. db.users.insertOne({ email: "[e-mail]", status: "active" })

C. db.users.updateOne({ email: "[e-mail]" }, { status: "active" }, { upsert: true })

D. db.users.updateMany({ email: "[e-mail]" }, { $set: { status: "active" } })

Solution

1. Step 1: Identify the correct update syntax with upsert

   To update or insert, use updateOne with a filter, an update using $set, and {upsert: true} option.

2. Step 2: Check each option

   db.users.updateOne({ email: "[e-mail]" }, { $set: { status: "active" } }, { upsert: true }) uses $set and upsert correctly. db.users.insertOne({ email: "[e-mail]", status: "active" }) only inserts, no update. db.users.updateOne({ email: "[e-mail]" }, { status: "active" }, { upsert: true }) misses $set operator, which replaces the whole document incorrectly. db.users.updateMany({ email: "[e-mail]" }, { $set: { status: "active" } }) updates many but no upsert.

3. Final Answer:

   db.users.updateOne({ email: "[e-mail]" }, { $set: { status: "active" } }, { upsert: true }) -> Option A

4. Quick Check:

   Use updateOne + $set + upsert: true [OK]

Hint: Use $set with upsert: true in updateOne to update or insert [OK]

Common Mistakes:

• Omitting $set causing document replacement
• Using insertOne which does not update
• Forgetting upsert option for insert fallback