Update Single Document using updateOne() in MongoDB

Learn how to update a single document using the updateOne() method in MongoDB.

MongoDB provides the following methods to update existing documents in a collection:

• db.collection.updateOne() - Modifies a single document in a collection.
• db.collection.updateMany() - Modifies one or more documents in a collection.

db.collection.updateOne()

Use the db.<collection>.updateOne() method to update a single document in a collection that matches with the specified filter criteria. It updates the first matching document even if multiple documents match with the criteria.

Syntax:

db.collection.updateOne(filter, document, options)

Parameters:

1. filter: The selection criteria for the update, same as find() method.
2. document: A document or pipeline that contains modifications to apply.
3. options: Optional. May contains options for update behavior. It includes upsert, writeConcern, collation, etc.

In the above syntax, db points to the current database, <collection> points is an existing collection name.

To demonstrate the update operation, insert the following sample documents in the employees collection.

db.employees.insertMany([
    { 
        _id:1,
        firstName: "John",
        lastName: "King",
        email: "[email protected]",
        salary: 5000
    },
    { 
        _id:2,
        firstName: "Sachin",
        lastName: "T",
        email: "[email protected]",
        salary: 8000
    },
    { 
        _id:3,
        firstName: "James",
        lastName: "Bond",
        email: "[email protected]",
        salary: 7500
    },
    { 
        _id:4,
        firstName: "Steve",
        lastName: "J",
        email: "[email protected]",
        salary: 7000
    },
    { 
        _id:5,
        firstName: "Kapil",
        lastName: "D",
        email: "[email protected]",
        salary: 4500
    },
    { 
        _id:6,
        firstName: "Amitabh",
        lastName: "B",
        email: "[email protected]",
        salary: 7000
    }
])

Update a Single Field

The following updates a single field in a single document in employees collection.

db.employees.updateOne({_id:1}, { $set: {firstName:'Morgan'}})

{
  acknowledged: true,
  insertedId: null,
  matchedCount: 1,
  modifiedCount: 1,
  upsertedCount: 0
}

In the above example, the first parameter is the filter criteria specified as a document, {_id:1} indicates that find a document whose _id is 1. The second parameter is used to specify fields and values to be modified on the matching document in the {<update-operator>: { field: value, field:value,... }} format. Use the update operator to specify what action to perform. Here we want to set the value of a field, so use $set operator to specify fields and updated values in {field:updated-value} format.{ $set: {firstName:'Morgan'}} modifies the firstName to "Morgan" to the first document that matches with the specified criteria {_id:1}.

In the output, matchedCount indicates the number of documents that matched with the criteria, and modifiedCount indicates the number of documents updated. The updateOne() method will always modify a single document.

Now, check whether it has updated a value or not using the findOne() method shown below.

db.employees.find({_id:1})

{
  _id: 1,
  firstName: 'Morgan',
  lastName: 'King',
  email: '[email protected]',
  salary: 5000
}

The updateOne() method adds the specified field if it does not exist in a matching document. For example, the following will add the location field.

db.employees.updateOne({firstName:"Steve"}, { $set: {location: "USA"}})

{
  acknowledged: true,
  insertedId: null,
  matchedCount: 1,
  modifiedCount: 1,
  upsertedCount: 0
}

Execute the following find() method to see the updated data.

db.employees.find({firstName:"Steve"})

{
    _id:4,
    firstName: "Steve",
    lastName: "J",
    email: "[email protected]",
    salary: 7000,
    location:"USA"
}

Use the $inc update operator to increase the value of the field by the specified amount.

db.employees.updateOne({firstName:"Steve"}, { $inc: {salary: 500}})

{
  acknowledged: true,
  insertedId: null,
  matchedCount: 1,
  modifiedCount: 1,
  upsertedCount: 0
}

Execute the following find() method to see the updated data.

db.employees.find({firstName:"Steve"})

{
    _id:4,
    firstName: "Steve",
    lastName: "J",
    email: "[email protected]",
    salary: 7500,
    location:"USA"
}

Update Multiple Fields

You can also specify multiple fields to update. The following updates email and lastName fields.

db.employees.updateOne({_id:2}, { $set: {lastName:"Tendulkar", email:"[email protected]"}})

{
  acknowledged: true,
  insertedId: null,
  matchedCount: 1,
  modifiedCount: 1,
  upsertedCount: 0
}

Execute the following find() method to see the updated data.

db.employees.find({_id:2})

{
    _id:2,
    firstName: "Sachin",
    lastName: "Tendulkar",
    email: "[email protected]",
    salary: 8000
}

The updateOne() method updates a single document only, even if it finds multiple documents. For example, the following updates the first document even if it returns multiple documents.

db.employees.updateOne({salary:7000}, { $set: {salary:7500}})

{
  acknowledged: true,
  insertedId: null,
  matchedCount: 1,
  modifiedCount: 1,
  upsertedCount: 0
} 

In the above example, the employees collection contains two documents that have salary:7000 field. However, the updateOne() modified a single document which is the first document from the matching result.

Upsert - Add if not Exist

Specify {upsert:true} as a third parameter in the UpdateOne() method. The upsert:true adds a new document if the matching document does not found.

db.employees.updateOne({firstName:"Heer"}, { $set: {lastName:"Patel", salary:2000}})

{
  acknowledged: true,
  insertedId: ObjectId("6172a2e9ce7d5ca09d6ab082"),
  matchedCount: 0,
  modifiedCount: 0,
  upsertedCount: 1
}

In the above example, MongoDB adds a new document with new _id, because it cannot find a document with the firstName:"Heer".

Update Operators

The following table lists the update operators which can be used with the updateOne() and updateMany() methods.

Visit Update Operators on MongoDB documentation.