How to manage documents in MongoDB

Using the insert() method

The insert() method allows you to insert one or more documents into the collection it is called on.

To insert a single document, pass the document to the method by calling it on the collection. Here, we insert a new document for a student named Ashley:

db.students.insert(
    {
        first_name: "Ashley",
        last_name: "Jenkins",
        dob: new Date("January 08, 2003"),
        grade_level: 8
    }
)

WriteResult({ "nInserted" : 1 })

If you want to insert more than one document at the same time, instead of passing a document to insert(), pass an array of documents. We can add two new documents for students named Brian and Leah:

db.students.insert(
    [
        {
            first_name: "Brian",
            last_name: "McMantis",
            dob: new Date("September 18, 2010"),
            grade_level: 2
        },
        {
            first_name: "Leah",
            last_name: "Drake",
            dob: new Date("October 03, 2009")
        }
    ]
)

BulkWriteResult({
        "writeErrors" : [ ],
        "writeConcernErrors" : [ ],
        "nInserted" : 2,
        "nUpserted" : 0,
        "nMatched" : 0,
        "nModified" : 0,
        "nRemoved" : 0,
        "upserted" : [ ]
})

Since we performed a bulk write operation, our return value is a BulkWriteResult instead of the WriteResult object we saw before.

While the insert() method is flexible, it has been deprecated in many MongoDB drivers in favor of the following two methods.

Using the insertOne() method

The insertOne() method can be used to insert a single document. Unlike the insert() method, it can only insert one document at a time, which makes its behavior a bit more predictable.

The syntax is the same as when you use insert() to add a single document. We can add another student named Naomi:

db.students.insertOne(
    {
        first_name: "Naomi",
        last_name: "Pyani"
    }
)

{
        "acknowledged" : true,
        "insertedId" : ObjectId("60e877914655cbf49ff7cb86")
}

Unlike with insert(), the insertOne() method returns a document containing some additional useful information. It confirms that the write was acknowledged by the cluster and it includes the object ID that was assigned to the document since we did not provide one.

Using the insertMany() method

To cover scenarios where you want to insert multiple documents at once, the insertMany() method is now recommended. Just as when inserting multiple documents with insert(), insertMany() takes an array of documents.

We can add three new students named Jasmine, Michael, and Toni:

db.students.insertMany(
    [
        {
            first_name: "Jasmine",
            last_name: "Took",
            dob: new Date("April 11, 2011")
        },
        {
            first_name: "Michael",
            last_name: "Rodgers",
            dob: new Date("February 25, 2008"),
            grade_level: 6
        },
        {
            first_name: "Toni",
            last_name: "Fowler"
        }
    ]
)

{
        "acknowledged" : true,
        "insertedIds" : [
                ObjectId("60e8792d4655cbf49ff7cb87"),
                ObjectId("60e8792d4655cbf49ff7cb88"),
                ObjectId("60e8792d4655cbf49ff7cb89")
        ]
}

As with insertOne(), insertMany() returns a document which acknowledges the write and provides an array containing the IDs that have been assigned to the inserted documents.

Update operators

Before we take a look at each of the methods to update documents, we should go over some of the update operators that are available.

• $currentDate: Sets a field's value to the current date, either as a date or timestamp type.
  • Syntax: { $currentDate: { <field>: <type>, ... } }
• $inc: Increments a field's value by a set amount.
  • Syntax: { $inc: { <field>: <amount>, ... } }
• $min: Updates a field's value if the specified value is less than the current value.
  • Syntax: { $min: { <field>: <value>, ... } }
• $max: Updates a field's value if the specified value is more than the current value.
  • Syntax: { $max: { <field>: <value>, ... } }
• $mul: Updates a field's value by multiplying it by the given number.
  • Syntax: { $mul: { <field>: <value>, ... } }
• $rename: Renames a field name to a new identifier.
  • Syntax: { $rename: { <field>: <new_name>, ... } }
• $set: Replaces the value of a field with the given value.
  • Syntax: { $set: { <field>: value, ... } }
• $setOnInsert: During upsert operations, sets the value of a field if a new document is being created and does nothing otherwise.
  • Syntax: { $setOnInsert: { <field>: <value>, ... } }
• $unset: Removes a field from the document.
  • Syntax: { $unset: { <field>: "", ... } }
• $: A placeholder for the first array element that satisfies the query.
  • Syntax: { <update_operator>: {<array>.$: <value> } }
• $[]: A placeholder for all array elements that satisfy the query.
  • Syntax: { <update_operator>: { <array>.$[]: <value> } }
• $addToSet: Adds values to the array unless they're already present.
  • Syntax: { $addToSet: { <field>: <value>, ... } }
• $pop: Removes the first or last element of an array.
  • Syntax: { $pop: { <field>: (-1 or 1), ... } }
• $pull: Removes all elements of an array that match a condition.
  • Syntax: { $pull: { <field>: <condition>, ... } }
• $push: Appends a value to an array.
  • Syntax: { $push: { <field>: <value>, ... } }
• $pullAll: Removes all of the specified elements from an array.
  • Syntax: { $pullAll: { <field>: [ <value>, ... ], ...} }
• $each: Modifies $addToSet and $push operators so that they add each element of an array instead of an array as a single element.
  • Syntax: { <update_operator>: { <field>: { $each: [ <value>, ... ] }, ... } }
• $position: Used with $each and specifies the position the $push operator should insert at.
  • Syntax: { $push: { <field>: { $each: [ <value>, ... ], $position: <num> } } }
• $slice: Used with $each and $push to limit the number of total elements in the array.
  • Syntax: { $push: { <field>: { $each: [ <value>, ... ], $slice: <num> } } }
• $sort: Used with $each and $push to sort array elements.
  • Syntax: { $push: { <field>: { $each: [ <value>, ... ], $sort: <sort_order> } } }

These various update operators allow you to update various fields of your documents in different ways.

Updating a single document in a collection

MongoDB's updateOne() method is used to update a single document within a collection. The method takes two required arguments as well as a document specifying optional arguments.

The first argument is a document that specifies the filter conditions that will be used to select documents. Since the updateOne() method modifies at most one document in a collection, the first document that satisfies the filter conditions will be used.

The second argument specifies the update operation that should be executed. The update operations given above can be specified here to alter the contents of the matched document.

The third argument is a document of various options to modify the behavior of the method. The most important potential values are:

• upsert: Turns the operation into an upsert procedure by inserting a new document if the filter does not match any existent documents.
• collation: A document that defines language-specific rules that should apply for the operation.

As an example, we can update a single student record that we filter by the _id field to ensure that we target the correct document. We can set the grade_level to a new value:

db.students.updateOne(
    { _id: ObjectId("60e8792d4655cbf49ff7cb89") },
    { $set: { grade_level: 3 } }
)

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

Updating multiple documents in a collection

MongoDB's updateMany() method works similar to the updateOne() method, but instead updates any document that matches the given filter instead of stopping after the first match.

The updateMany() syntax exactly follows the updateOne() syntax, so the only difference is the scope of the operation.

As an example, if we want to change all of the instances of "composition" to "writing" in the subjects array in our teachers collection documents, we could use something like this:

db.teachers.updateMany(
    { subject: "composition" },
    { $set: { "subjects.$": "writing" } }
)

{ "acknowledged" : true, "matchedCount" : 3, "modifiedCount" : 3 }

If you check the documents, each instance of "composition" should have been replaced with "writing":

db.teachers.find()

{ "_id" : ObjectId("60eddca65eb74f5c676f3baa"), "first_name" : "Nancy", "last_name" : "Smith", "subjects" : [ "vocabulary", "pronunciation" ] }
{ "_id" : ObjectId("60eddca65eb74f5c676f3bab"), "first_name" : "Ronald", "last_name" : "Taft", "subjects" : [ "literature", "grammar", "writing" ] }
{ "_id" : ObjectId("60eddca65eb74f5c676f3bac"), "first_name" : "Casey", "last_name" : "Meyers", "subjects" : [ "literature", "writing", "grammar" ] }
{ "_id" : ObjectId("60eddca65eb74f5c676f3bad"), "first_name" : "Rebecca", "last_name" : "Carrie", "subjects" : [ "grammar", "literature" ] }
{ "_id" : ObjectId("60eddca65eb74f5c676f3bae"), "first_name" : "Sophie", "last_name" : "Daggs", "subjects" : [ "literature", "writing", "grammar", "vocabulary", "pronunciation" ] }

Replacing a document

The replaceOne() method works similar to the updateOne() method, but replaces the entire document instead of updating individual fields. The syntax is the same as the previous two commands.

For instance, if Nancy Smith leaves your school and you replace her with a teacher named Clara Newman who teaches literature, you could type the following:

db.teachers.replaceOne(
    {
        $and: [
            { first_name: "Nancy" },
            { last_name: "Smith" }
        ]
    },
    {
        first_name: "Clara",
        last_name: "Newman",
        subjects: [ "literature" ]
    }
)

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

You can see that the matched document has been removed and that the specified document has replaced it:

db.teachers.find()

{ "_id" : ObjectId("60eddca65eb74f5c676f3baa"), "first_name" : "Clara", "last_name" : "Newman", "subjects" : [ "literature" ] }
{ "_id" : ObjectId("60eddca65eb74f5c676f3bab"), "first_name" : "Ronald", "last_name" : "Taft", "subjects" : [ "literature", "grammar", "writing" ] }
{ "_id" : ObjectId("60eddca65eb74f5c676f3bac"), "first_name" : "Casey", "last_name" : "Meyers", "subjects" : [ "literature", "writing", "grammar" ] }
{ "_id" : ObjectId("60eddca65eb74f5c676f3bad"), "first_name" : "Rebecca", "last_name" : "Carrie", "subjects" : [ "grammar", "literature" ] }
{ "_id" : ObjectId("60eddca65eb74f5c676f3bae"), "first_name" : "Sophie", "last_name" : "Daggs", "subjects" : [ "literature", "writing", "grammar", "vocabulary", "pronunciation" ] }