Skip to main content

MongoDB updateOne

Introduction​

The updateOne() method is one of the fundamental update operations in MongoDB. It allows you to modify a single document that matches a specified filter. This is part of MongoDB's CRUD (Create, Read, Update, Delete) operations and is essential for maintaining data in your database.

Unlike the update() method (which is deprecated), updateOne() is designed to modify only the first document that matches your filter criteria, even if multiple documents match. This precision makes it a safer choice for many applications where you want to ensure only one document is changed.

Syntax​

The basic syntax for the updateOne() method is:

javascript
db.collection.updateOne(
   <filter>,
   <update>,
   {
     upsert: <boolean>,
     writeConcern: <document>,
     collation: <document>,
     arrayFilters: [ <filterdocument1>, ... ],
     hint: <document|string>
   }
)

Let's break down these parameters:

  • filter: A document that specifies selection criteria (similar to the WHERE clause in SQL)
  • update: A document that specifies the modifications to apply
  • upsert: Optional. When set to true, creates a new document if no document matches the filter
  • writeConcern: Optional. Describes the level of acknowledgment for write operations
  • collation: Optional. Specifies language-specific rules for string comparison
  • arrayFilters: Optional. Specifies which array elements to modify for array updates
  • hint: Optional. Specifies the index to use for the operation

Update Operators​

MongoDB provides several operators to help you update documents effectively:

Field Update Operators​

  • $set: Sets the value of a field
  • $unset: Removes the specified field
  • $inc: Increments the value of a field by a specified amount
  • $mul: Multiplies the value of a field by a specified amount
  • $rename: Renames a field
  • $min: Updates the field if the specified value is less than the current value
  • $max: Updates the field if the specified value is greater than the current value

Array Update Operators​

  • $push: Adds an element to an array
  • $pop: Removes the first or last element of an array
  • $pull: Removes elements from an array that match a specified query
  • $addToSet: Adds elements to an array only if they don't already exist

Basic Examples​

Example 1: Using $set to Update a Field​

Let's say we have a collection of users, and we want to update a user's email address:

javascript
// Our sample document
db.users.insertOne({
  name: "John Doe",
  email: "[email protected]",
  age: 28,
  tags: ["developer", "mongodb"]
});

// Update John's email address
db.users.updateOne(
  { name: "John Doe" },
  { $set: { email: "[email protected]" } }
);

Output:

javascript
{
  "acknowledged": true,
  "matchedCount": 1,
  "modifiedCount": 1
}

After this operation, John's document would look like:

javascript
{
  "_id": ObjectId("..."),
  "name": "John Doe",
  "email": "[email protected]",
  "age": 28,
  "tags": ["developer", "mongodb"]
}

Example 2: Using $inc to Increment a Value​

Let's increment John's age:

javascript
// Increment John's age by 1
db.users.updateOne(
  { name: "John Doe" },
  { $inc: { age: 1 } }
);

Output:

javascript
{
  "acknowledged": true,
  "matchedCount": 1,
  "modifiedCount": 1
}

After this operation, John's document would be:

javascript
{
  "_id": ObjectId("..."),
  "name": "John Doe",
  "email": "[email protected]",
  "age": 29,
  "tags": ["developer", "mongodb"]
}

Example 3: Using $push to Add to an Array​

Let's add a new tag to John's tags array:

javascript
// Add a new tag to John's tags
db.users.updateOne(
  { name: "John Doe" },
  { $push: { tags: "javascript" } }
);

Output:

javascript
{
  "acknowledged": true,
  "matchedCount": 1,
  "modifiedCount": 1
}

After this operation, John's document would be:

javascript
{
  "_id": ObjectId("..."),
  "name": "John Doe",
  "email": "[email protected]",
  "age": 29,
  "tags": ["developer", "mongodb", "javascript"]
}

Advanced Examples​

Example 4: Using upsert​

The upsert option creates a new document if no document matches the filter:

javascript
// Update Jane's document or create it if it doesn't exist
db.users.updateOne(
  { name: "Jane Smith" },
  { 
    $set: { 
      email: "[email protected]",
      age: 25,
      tags: ["designer"] 
    }
  },
  { upsert: true }
);

Output:

javascript
{
  "acknowledged": true,
  "matchedCount": 0,
  "modifiedCount": 0,
  "upsertedId": ObjectId("...")
}

Since Jane's document didn't exist, a new one was created:

javascript
{
  "_id": ObjectId("..."),
  "name": "Jane Smith",
  "email": "[email protected]",
  "age": 25,
  "tags": ["designer"]
}

Example 5: Using $addToSet for Unique Array Values​

The $addToSet operator adds an element to an array only if it doesn't already exist:

javascript
// Add "mongodb" to John's tags (won't be duplicated)
db.users.updateOne(
  { name: "John Doe" },
  { $addToSet: { tags: "mongodb" } }
);

Output:

javascript
{
  "acknowledged": true,
  "matchedCount": 1,
  "modifiedCount": 0  // No modification because "mongodb" already exists
}

Example 6: Using arrayFilters to Update Specific Array Elements​

Let's say we have a collection of blog posts with comments:

javascript
db.posts.insertOne({
  title: "MongoDB Basics",
  comments: [
    { user: "Alice", text: "Great post!", rating: 4 },
    { user: "Bob", text: "Needs more examples", rating: 3 }
  ]
});

We can update a specific comment using arrayFilters:

javascript
db.posts.updateOne(
  { title: "MongoDB Basics" },
  { $set: { "comments.$[elem].text": "Excellent post!" } },
  { arrayFilters: [{ "elem.user": "Alice" }] }
);

Output:

javascript
{
  "acknowledged": true,
  "matchedCount": 1,
  "modifiedCount": 1
}

After this operation, the document would be:

javascript
{
  "_id": ObjectId("..."),
  "title": "MongoDB Basics",
  "comments": [
    { "user": "Alice", "text": "Excellent post!", "rating": 4 },
    { "user": "Bob", "text": "Needs more examples", "rating": 3 }
  ]
}

Real-world Applications​

Application 1: User Profile Updates​

In a web application, users often update their profiles:

javascript
// Update user profile
db.users.updateOne(
  { _id: ObjectId("user_id_here") },
  { 
    $set: { 
      "profile.displayName": "Johnny",
      "profile.bio": "MongoDB enthusiast",
      "lastUpdated": new Date() 
    }
  }
);

Application 2: Shopping Cart Management​

In an e-commerce application, you might need to update quantities in a shopping cart:

javascript
// Increment item quantity in cart
db.carts.updateOne(
  { 
    userId: ObjectId("user_id_here"), 
    "items.productId": ObjectId("product_id_here") 
  },
  { $inc: { "items.$.quantity": 1 } }
);

Application 3: Document Status Changes​

When tracking task status in a project management app:

javascript
// Mark a task as completed
db.tasks.updateOne(
  { _id: ObjectId("task_id_here") },
  { 
    $set: { 
      status: "completed", 
      completedAt: new Date() 
    }
  }
);

Best Practices​

  1. Be specific with your filters: The more specific your filter, the less chance of unintended updates.

  2. Use atomic operators: MongoDB's update operators like $set and $inc are atomic, ensuring consistent updates even with concurrent operations.

  3. Consider using upsert wisely: The upsert option is powerful but can create unexpected documents if your filter is too general.

  4. Use array operators appropriately: Choose the right operator for array updates ($push, $pull, $addToSet) based on your needs.

  5. Validate the update result: Always check the modifiedCount to confirm if your update was applied.

Common Gotchas​

  1. Replacing entire documents: Unlike the old update() method, updateOne() with a plain document (without operators) will completely replace the matched document except for the _id field.

    javascript
    // CAUTION: This will replace John's entire document!
    db.users.updateOne(
      { name: "John Doe" },
      { name: "John Doe", email: "[email protected]" }
    );

    // Better approach - use $set:
    db.users.updateOne(
      { name: "John Doe" },
      { $set: { email: "[email protected]" } }
    );

  2. Field doesn't exist: Using operators like $inc on fields that don't exist will create them with appropriate starting values.

  3. Updating arrays: When updating elements in an array, you need to be careful about the syntax. The positional $ operator only works when the array element is part of the query criteria.

Summary​

The updateOne() method in MongoDB is a powerful tool for modifying single documents with precision. Key points to remember:

  • It updates only the first document that matches the filter criteria
  • Update operators like $set, $inc, $push provide flexibility in how you modify documents
  • The upsert option allows creating new documents when no match is found
  • Array updates require special consideration, with operators like $push, $pull, and $addToSet

By mastering updateOne(), you can efficiently maintain your MongoDB data with minimal code and maximum precision.

Exercises​

  1. Create a collection of products and use updateOne() with $inc to decrease a product's quantity by 1.

  2. Use updateOne() with the upsert option to either update an existing student's grade or add a new student.

  3. Create a blog post document with an array of comments, then use updateOne() with arrayFilters to update a specific comment.

  4. Use updateOne() with $push and $each to add multiple tags to a document in a single operation.

  5. Create a user document with a nested address object, then use updateOne() with dot notation to update only the city field in the address.

Additional Resources​


If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)