db.collection.findAndModify()

fields Projection

The fields option takes a document in the following form:

{ field1: <value>, field2: <value> ... }

Upsert with Unique Index

Upserts can create duplicate documents, unless there is a unique index to prevent duplicates.

Consider an example where no document with the name Andy exists and multiple clients issue the following command at roughly the same time:

db.people.findAndModify(
   {
     query: { name: "Andy" },
     update: { $inc: { score: 1 } },
     upsert: true
   }
)

If all findOneAndUpdate() operations finish the query phase before any client successfully inserts data, and there is no unique index on the name field, each findOneAndUpdate() operation may result in an insert, creating multiple documents with name: Andy.

A unique index on the name field ensures that only one document is created. With a unique index in place, the multiple findOneAndUpdate() operations now exhibit the following behavior:

• Exactly one findOneAndUpdate() operation will successfully insert a new document.

• Other findOneAndUpdate() operations either update the newly-inserted document or fail due to a unique key collision.

  In order for other findOneAndUpdate() operations to update the newly-inserted document, all of the following conditions must be met:

  • The target collection has a unique index that would cause a duplicate key error.

  • The update operation is not updateMany or multi is false.

  • The update match condition is either:

    • A single equality predicate. For example { "fieldA" : "valueA" }

    • A logical AND of equality predicates. For example { "fieldA" : "valueA", "fieldB" : "valueB" }

  • The fields in the equality predicate match the fields in the unique index key pattern.

  • The update operation does not modify any fields in the unique index key pattern.

The following table shows examples of upsert operations that, when a key collision occurs, either result in an update or fail.

{ name : 1 }

db.people.updateOne(
   { name: "Andy" },
   { $inc: { score: 1 } },
   { upsert: true }
)

{ name : 1 }

db.people.updateOne(
   { name: { $ne: "Joe" } },
   { $set: { name: "Andy" } },
   { upsert: true }
 )

{ name : 1 }

db.people.updateOne(
  { name: "Andy", email: "andy@xyz.com" },
  { $set: { active: false } },
  { upsert: true }
)

Sharded Collections

When using findAndModify against a sharded collection, the query must contain an equality condition on shard key.

Starting in version 4.4, documents in a sharded collection can be missing the shard key fields. To target a document that is missing the shard key, you can use the null equality match in conjunction with another filter condition (such as on the _id field). For example:

{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key

Document Validation

The db.collection.findAndModify() method adds support for the bypassDocumentValidation option, which lets you bypass document validation when inserting or updating documents in a collection with validation rules.

Comparisons with the update Method

When updating a document, db.collection.findAndModify() and the update() method operate differently:

• By default, both operations modify a single document. However, the update() method with its multi option can modify more than one document.

• If multiple documents match the update criteria, for db.collection.findAndModify(), you can specify a sort to provide some measure of control on which document to update.

  With the default behavior of the update() method, you cannot specify which single document to update when multiple documents match.

• By default, db.collection.findAndModify() returns the pre-modified version of the document. To obtain the updated document, use the new option.

  The update() method returns a WriteResult() object that contains the status of the operation. To return the updated document, use the find() method. However, other updates may have modified the document between your update and the document retrieval. Also, if the update modified only a single document but multiple documents matched, you will need to use additional logic to identify the updated document.

When modifying a single document, both db.collection.findAndModify() and the update() method atomically update the document. See Atomicity and Transactions for more details about interactions and order of operations of these methods.

Transactions

db.collection.findAndModify() can be used inside distributed transactions.

Update and Return

The following method updates and returns an existing document in the people collection where the document matches the query criteria:

db.people.findAndModify({
    query: { name: "Tom", state: "active", rating: { $gt: 10 } },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } }
})

This method performs the following actions:

1. The query finds a document in the people collection where the name field has the value Tom, the state field has the value active and the rating field has a value greater than 10.

2. The sort orders the results of the query in ascending order. If multiple documents meet the query condition, the method will select for modification the first document as ordered by this sort.

3. The update increments the value of the score field by 1.

4. The method returns the original (i.e. pre-modification) document selected for this update:

   {
     "_id" : ObjectId("50f1e2c99beb36a0f45c6453"),
     "name" : "Tom",
     "state" : "active",
     "rating" : 100,
     "score" : 5
   }

   To return the updated document, add the new:true option to the method.

   If no document matched the query condition, the method returns null.

Upsert

The following method includes the upsert: true option for the update operation to either update a matching document or, if no matching document exists, create a new document:

db.people.findAndModify({
    query: { name: "Gus", state: "active", rating: 100 },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } },
    upsert: true
})

If the method finds a matching document, the method performs an update.

If the method does not find a matching document, the method creates a new document. Because the method included the sort option, it returns an empty document { } as the original (pre-modification) document:

{ }

If the method did not include a sort option, the method returns null.

null

Return New Document

The following method includes both the upsert: true option and the new:true option. The method either updates a matching document and returns the updated document or, if no matching document exists, inserts a document and returns the newly inserted document in the value field.

In the following example, no document in the people collection matches the query condition:

db.people.findAndModify({
    query: { name: "Pascal", state: "active", rating: 25 },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } },
    upsert: true,
    new: true
})

The method returns the newly inserted document:

{
   "_id" : ObjectId("50f49ad6444c11ac2448a5d6"),
   "name" : "Pascal",
   "rating" : 25,
   "score" : 1,
   "state" : "active"
}

Sort and Remove

By including a sort specification on the rating field, the following example removes from the people collection a single document with the state value of active and the lowest rating among the matching documents:

db.people.findAndModify(
   {
     query: { state: "active" },
     sort: { rating: 1 },
     remove: true
   }
)

The method returns the deleted document:

{
   "_id" : ObjectId("52fba867ab5fdca1299674ad"),
   "name" : "XYZ123",
   "score" : 1,
   "state" : "active",
   "rating" : 3
}

Specify Collation

Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.

A collection myColl has the following documents:

{ _id: 1, category: "café", status: "A" }
{ _id: 2, category: "cafe", status: "a" }
{ _id: 3, category: "cafE", status: "a" }

The following operation includes the collation option:

db.myColl.findAndModify({
    query: { category: "cafe", status: "a" },
    sort: { category: 1 },
    update: { $set: { status: "Updated" } },
    collation: { locale: "fr", strength: 1 }
});

The operation returns the following document:

{ "_id" : 1, "category" : "café", "status" : "A" }

Specify arrayFilters for an Array Update Operations

Starting in MongoDB 3.6, when updating an array field, you can specify arrayFilters that determine which array elements to update.

db.students.insert([
   { "_id" : 1, "grades" : [ 95, 92, 90 ] },
   { "_id" : 2, "grades" : [ 98, 100, 102 ] },
   { "_id" : 3, "grades" : [ 95, 110, 100 ] }
])

db.students.findAndModify({
   query: { grades: { $gte: 100 } },
   update: { $set: { "grades.$[element]" : 100 } },
   arrayFilters: [ { "element": { $gte: 100 } } ]
})

{ "_id" : 1, "grades" : [ 95, 92, 90 ] }
{ "_id" : 2, "grades" : [ 98, 100, 100 ] }
{ "_id" : 3, "grades" : [ 95, 110, 100 ] }

db.students2.insert([
   {
      "_id" : 1,
      "grades" : [
         { "grade" : 80, "mean" : 75, "std" : 6 },
         { "grade" : 85, "mean" : 90, "std" : 4 },
         { "grade" : 85, "mean" : 85, "std" : 6 }
      ]
   },
   {
      "_id" : 2,
      "grades" : [
         { "grade" : 90, "mean" : 75, "std" : 6 },
         { "grade" : 87, "mean" : 90, "std" : 3 },
         { "grade" : 85, "mean" : 85, "std" : 4 }
      ]
   }
])

db.students2.findAndModify({
   query: { _id : 1 },
   update: { $set: { "grades.$[elem].mean" : 100 } },
   arrayFilters: [ { "elem.grade": { $gte: 85 } } ]
})

{
   "_id" : 1,
   "grades" : [
      { "grade" : 80, "mean" : 75, "std" : 6 },
      { "grade" : 85, "mean" : 100, "std" : 4 },
      { "grade" : 85, "mean" : 100, "std" : 6 }
   ]
}
{
   "_id" : 2,
   "grades" : [
      { "grade" : 90, "mean" : 75, "std" : 6 },
      { "grade" : 87, "mean" : 90, "std" : 3 },
      { "grade" : 85, "mean" : 85, "std" : 4 }
   ]
}

Use an Aggregation Pipeline for Updates

Starting in MongoDB 4.2, db.collection.findAndModify() can accept an aggregation pipeline for the update. The pipeline can consist of the following stages:

• $addFields and its alias $set

• $project and its alias $unset

• $replaceRoot and its alias $replaceWith.

Using the aggregation pipeline allows for a more expressive update statement, such as expressing conditional updates based on current field values or updating one field using the value of another field(s).

For example, create a collection students2 with the following documents:

db.students2.insert([
   {
      "_id" : 1,
      "grades" : [
         { "grade" : 80, "mean" : 75, "std" : 6 },
         { "grade" : 85, "mean" : 90, "std" : 4 },
         { "grade" : 85, "mean" : 85, "std" : 6 }
      ]
   },
   {
      "_id" : 2,
      "grades" : [
         { "grade" : 90, "mean" : 75, "std" : 6 },
         { "grade" : 87, "mean" : 90, "std" : 3 },
         { "grade" : 85, "mean" : 85, "std" : 4 }
      ]
   }
])

The following operation finds a document where the _id field equals 1 and uses an aggregation pipeline to calculate a new field total from the grades field:

db.students2.findAndModify( {
   query: {  "_id" : 1 },
   update: [ { $set: { "total" : { $sum: "$grades.grade" } } } ],  // The $set stage is an alias for ``$addFields`` stage
   new: true
} )

The operation returns the updated document:

{
   "_id" : 1,
   "grades" : [ { "grade" : 80, "mean" : 75, "std" : 6 }, { "grade" : 85, "mean" : 90, "std" : 4 }, { "grade" : 85, "mean" : 85, "std" : 6 } ],
   "total" : 250
}