How to Update Nested Field in MongoDB: Syntax and Examples

To update a nested field in MongoDB, use the updateOne() or updateMany() method with the dot notation to specify the nested field path, like {"parent.child": value}. This lets you target and change values inside embedded documents without replacing the whole document.

Syntax

Use the updateOne() or updateMany() method with a filter to find the document(s) and an update object using $set to change the nested field. The nested field is specified using dot notation, where each level is separated by a dot.

• filter: Selects the document(s) to update.
• $set: Operator to assign a new value.
• "parent.child": Dot notation path to the nested field.

mongodb

db.collection.updateOne(
  { _id: 1 },
  { $set: { "parent.child": "new value" } }
)

Example

This example updates the nested field address.city in a user document to "New York".

mongodb

db.users.insertOne({
  _id: 1,
  name: "Alice",
  address: {
    city: "Los Angeles",
    zip: "90001"
  }
})

// Update nested field
const result = db.users.updateOne(
  { _id: 1 },
  { $set: { "address.city": "New York" } }
)

// Verify update
const updatedDoc = db.users.findOne({ _id: 1 })
printjson(updatedDoc)

Output

{
  "_id" : 1,
  "name" : "Alice",
  "address" : {
    "city" : "New York",
    "zip" : "90001"
  }
}

Common Pitfalls

Common mistakes when updating nested fields include:

• Not using dot notation, which replaces the entire nested object instead of just one field.
• Using $set without specifying the full path, causing unexpected overwrites.
• Trying to update a nested field that does not exist without creating it explicitly.

mongodb

/* Wrong: replaces whole address object */
db.users.updateOne(
  { _id: 1 },
  { $set: { address: { city: "Chicago" } } }
)

/* Right: updates only city field inside address */
db.users.updateOne(
  { _id: 1 },
  { $set: { "address.city": "Chicago" } }
)

Quick Reference

Operation	Syntax Example	Description
Update nested field	db.collection.updateOne({ _id: 1 }, { $set: { "parent.child": value } })	Updates a nested field using dot notation.
Update multiple nested fields	db.collection.updateOne({ _id: 1 }, { $set: { "parent.child1": val1, "parent.child2": val2 } })	Updates multiple nested fields at once.
Create nested field if missing	db.collection.updateOne({ _id: 1 }, { $set: { "parent.newChild": val } })	Creates the nested field if it does not exist.
Replace whole nested object (avoid)	db.collection.updateOne({ _id: 1 }, { $set: { parent: { child: val } } })	Replaces the entire nested object, not just one field.

Key Takeaways

Use dot notation with $set to update nested fields without replacing the whole object.

Always specify the full path to the nested field to avoid overwriting unintended data.

MongoDB will create the nested field if it does not exist when using $set with dot notation.

Avoid setting the entire nested object unless you want to replace it completely.

Test updates on sample data to ensure only intended fields are changed.