findAndModify

lastErrorObject

The lastErrorObject embedded document contains the following fields:lastErrorObject嵌入文档包含以下字段：

value

For remove operations, value contains the removed document if the query matches a document. 对于remove操作，如果查询与文档匹配，则值包含删除的文档。If the query does not match a document to remove, value contains null.如果查询与要删除的文档不匹配，则value包含null。

For update operations, the value embedded document contains the following:对于update操作，value嵌入文档包含以下内容：

• If the new parameter is not set or is false:如果new参数未设置或为false：

  • the pre-modification document if the query matches a document;如果查询与文档匹配，则预修改文档；
  • otherwise, null.否则为null。

• If new is true:如果new为true：

  • the modified document if the query returns a match;如果查询返回匹配，则修改后的文档；
  • the inserted document if upsert: true and no document matches the query;如果upsert为true，而插入的文档与查询不匹配；
  • otherwise, null.否则为null。

Upsert with Unique Index具有唯一索引的升级

When using the upsert: true option with the findAndModify command, and not using a unique index on the query field(s), multiple instances of a findAndModify operation with similar query field(s) could result in duplicate documents being inserted in certain circumstances.当在findAndModify命令中使用upsert:true选项，而不对查询字段使用唯一索引时，具有相似查询字段的findAndModify操作的多个实例可能会导致在某些情况下插入重复的文档。

Consider an example where no document with the name Andy exists and multiple clients issue the following command at roughly the same time:考虑一个示例，其中不存在名为Andy的文档，并且多个客户端大致同时发出以下命令：

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

If all findAndModify operations finish the query phase before any client successfully inserts data, and there is no unique index on the name field, each findAndModify operation may result in an insert, creating multiple documents with name: Andy.如果所有findAndModify操作都在任何客户端成功插入数据之前完成了查询阶段，并且name字段上没有唯一的索引，则每个findAndModify操作可能会导致插入，从而创建多个name: Andy的文档。

To ensure that only one such document is created, and the other findAndModify operations update this new document instead, create a unique index on the name field. 为了确保只创建一个这样的文档，而其他findAndModify操作会更新这个新文档，请在名称字段上创建一个唯一的索引。This guarantees that only one document with name: Andy is permitted in the collection.这保证了集合中只允许一个名为Andy的文档。

With this unique index in place, the multiple findAndModify operations now exhibit the following behavior:有了这个唯一的索引，多个findAndModify操作现在表现出以下行为：

• Exactly one findAndModify operation will successfully insert a new document.只有一个findAndModify操作才能成功插入新文档。
• All other findAndModify operations will update the newly-inserted document, incrementing the score value.所有其他ffindAndModify操作都将更新新插入的文档，增加score值。

Sharded Collections分片集合

To use findAndModify on a sharded collection, the query filter must include an equality condition on the shard key.要在分片集合上使用findAndModify，查询筛选器必须在分片键上包含相等条件。

Starting in version 4.4, documents in a sharded collection can be missing the shard key fields. 从4.4版开始，分片集合中的文档可能缺少分片键字段。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). 要以缺少分片键的文档为目标，可以将null相等匹配与另一个筛选条件（如_id字段）结合使用。For Example:例如：

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

Document Validation文档验证

The findAndModify command adds support for the bypassDocumentValidation option, which lets you bypass document validation when inserting or updating documents in a collection with validation rules.findAndModify命令添加了对bypassDocumentValidation选项的支持，该选项允许您在使用验证规则插入或更新集合中的文档时绕过文档验证。

Comparisons with the update Method与update方法的比较

When updating a document, findAndModify and the updateOne() method operate differently:更新文档时，findAndModify和updateOne()方法的操作方式不同：

• If multiple documents match the update criteria, for findAndModify, you can specify a sort to provide some measure of control on which document to update.如果多个文档符合更新条件，对于findAndModify，您可以指定一种排序，以提供对要更新的文档的某种控制措施。

  updateOne() updates the first document that matches.更新匹配的第一个文档。

• By default, findAndModify returns an object that contains the pre-modified version of the document, as well as the status of the operation. 默认情况下，findAndModify返回一个对象，该对象包含文档的预修改版本以及操作的状态。To obtain the updated document, use the new option.要获取更新的文档，请使用new选项。

  The updateOne() method returns a WriteResult() object that contains the status of the operation.updateOne()方法返回包含操作状态的WriteResult()对象。

  To return the updated document, use the find() method. 要返回更新的文档，请使用find()方法。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 findAndModify and the updateOne() method atomically update the document. 修改单个文档时，findAndModify和updateOne()方法都会自动更新文档。See Atomicity and Transactions for more details about interactions and order of operations of these methods.有关这些方法的交互和操作顺序的更多详细信息，请参阅原子性和事务。

Transactions事务

findAndModify can be used inside multi-document transactions.可以在多文档事务中使用。

Update and Return更新并返回

The following command updates an existing document in the people collection where the document matches the query criteria:以下命令将更新people集合中与query条件匹配的现有文档：

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

This command 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.query在people集合中找到一个文档，其中name字段的值为Tom，state字段的值是active，rating字段的值大于10。
2. The sort orders the results of the query in ascending order. sort以升序排列查询结果。If multiple documents meet the query condition, the command will select for modification the first document as ordered by this sort.如果多个文档满足query条件，该命令将选择按此排序排序的第一个文档进行修改。
3. The update increments the value of the score field by 1.update将score字段的值increments1。

4. The command returns a document with the following fields:该命令返回包含以下字段的文档：

   • The lastErrorObject field that contains the details of the command, including the field updatedExisting which is true, and包含命令详细信息的lastErrorObject字段，包括字段updatedExisting（为true），以及

   • The value field that contains the original (i.e. pre-modification) document selected for this update:包含为此更新选择的原始（即修改前）文档的value字段：

     {
       "lastErrorObject" : {
          "connectionId" : 1,
          "updatedExisting" : true,
          "n" : 1,
          "syncMillis" : 0,
          "writtenTo" : null,
          "err" : null,
          "ok" : 1
       },
       value" : {
     
         " _id" : ObjectId(" 54f62d2885e4be1f982b9c9c"),
     
         " name" : " Tom",
     
         " state" : " active",
     
         " rating" : 100,
     
         " score" : 5
       },
       " ok" : 1
     }

To return the modified document in the value field, add the new:true option to the command.要在value字段中返回修改后的文档，请在命令中添加new:true选项。

If no document match the query condition, the command returns a document that contains null in the value field:如果没有与query条件匹配的文档，该命令将返回一个在value字段中包含null的文档：

{ "value" : null, "ok" : 1 }

mongosh and many drivers provide a findAndModify() helper method. mongosh和许多驱动程序都提供了findAndModify()助手方法。Using the shell helper, this previous operation can take the following form:使用shell助手，前面的操作可以采用以下形式：

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

However, the findAndModify() shell helper method returns only the unmodified document, or if new is true, the modified document.但是，findAndModify()shell助手方法只返回未修改的文档，如果new为true，则返回修改后的文档。

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

upsert: true

The following findAndModify command 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:以下findAndModify命令包含upsert:true选项，用于更新操作，以更新匹配的文档，或者如果不存在匹配的文档则创建新文档：

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

If the command finds a matching document, the command performs an update.如果该命令找到匹配的文档，该命令将执行更新。

If the command does not find a matching document, the update with upsert: true operation results in an insertion and returns a document with the following fields:如果命令未找到匹配的文档，则upsert:true操作的update将导致插入，并返回包含以下字段的文档：

• The lastErrorObject field that contains the details of the command, including the field upserted that contains the _id value of the newly inserted document, and包含命令详细信息的lastErrorObject字段，包括包含新插入文档的_id值的upserted字段，以及
• The value field containing null.包含null的value字段。

{
  "value" : null,
  "lastErrorObject" : {
     "updatedExisting" : false,
     "n" : 1,
     "upserted" : ObjectId("54f62c8bc85d4472eadea26f")
  },
  "ok" : 1
}

Return New Document返回新文档

The following findAndModify command includes both upsert: true option and the new:true option. 以下findAndModify命令包括upsert:true选项和new:true命令。The command 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.该命令更新匹配的文档并返回更新的文档，或者如果不存在匹配的文档，则插入文档并在value字段中返回新插入的文档。

In the following example, no document in the people collection matches the query condition:在下面的示例中，people集合中没有与query条件匹配的文档：

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

The command returns the newly inserted document in the value field:该命令在value字段中返回新插入的文档：

{
  "lastErrorObject" : {
     "connectionId" : 1,
     "updatedExisting" : false,
     "upserted" : ObjectId("54f62bbfc85d4472eadea26d"),
     "n" : 1,
     "syncMillis" : 0,
     "writtenTo" : null,
     "err" : null,
     "ok" : 1
  },
  "value" : {
     "_id" : ObjectId("54f62bbfc85d4472eadea26d"),
     "name" : "Pascal",
     "rating" : 25,
     "state" : "active",
     "score" : 1
  },
  "ok" : 1
}

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:通过在rating字段中包含sort规范，以下示例将从people集合中删除state值为active且rating最低的匹配文档：

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

The command returns the deleted document:该命令返回已删除的文档：

{
  "lastErrorObject" : {
     "connectionId" : 1,
     "n" : 1,
     "syncMillis" : 0,
     "writtenTo" : null,
     "err" : null,
     "ok" : 1
  },
  "value" : {
     "_id" : ObjectId("54f62a6785e4be1f982b9c9b"),
     "name" : "XYZ123",
     "score" : 1,
     "state" : "active",
     "rating" : 3
  },
  "ok" : 1
}

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:myColl集合包含以下文档：

{ _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:以下操作包括collation选项：

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

The operation returns the following document:该操作将返回以下文档：

{
   "lastErrorObject" : {
      "updatedExisting" : true,
      "n" : 1
   },
   "value" : {
      "_id" : 1,
      "category" : "café",
      "status" : "A"
   },
   "ok" : 1
}

Array Update Operations with arrayFilters使用arrayFilters的数组更新操作

Starting in MongoDB 3.6, when updating an array field, you can specify arrayFilters that determine which array elements to update.从MongoDB 3.6开始，在更新数组字段时，可以指定arrayFilters来确定要更新的数组元素。

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

db.runCommand(
   {
     findAndModify: "students",
     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.insertMany( [
   {
      "_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.runCommand(
   {
     findAndModify: "students2",
     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, findAndModify can accept an aggregation pipeline for the update. 从MongoDB 4.2开始，findAndModify可以接受用于更新的聚合管道。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:例如，使用以下文档创建一个集合students2：

db.students2.insertMany( [
   {
      "_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:以下操作查找_id字段等于1的文档，并使用聚合管道从grades字段计算新的字段total：

db.runCommand(
   {
     findAndModify: "students2",
     query: {  "_id" : 1 },
     update: [ { $set: { "total" : { $sum: "$grades.grade" } } } ],
     new: true
   }
)

After the operation, the collection has the following documents:操作后，集合具有以下文档：

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

Specify hint for findAndModify Operations指定findAndModify操作的hint

In mongosh, create a members collection with the following documents:在mongosh中，使用以下文档创建members集合：

db.members.insertMany( [
   { "_id" : 1, "member" : "abc123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
   { "_id" : 2, "member" : "xyz123", "status" : "A", "points" : 60,  "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" },
   { "_id" : 3, "member" : "lmn123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
   { "_id" : 4, "member" : "pqr123", "status" : "D", "points" : 20,  "misc1" : "Deactivated", "misc2" : null },
   { "_id" : 5, "member" : "ijk123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
   { "_id" : 6, "member" : "cde123", "status" : "A", "points" : 86,  "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" }
] )

Create the following indexes on the collection:在集合上创建以下索引：

db.members.createIndex( { status: 1 } )
db.members.createIndex( { points: 1 } )

The following operation explicitly hints to use the index { status: 1 }:以下操作明确提示使用索引{ status: 1 }：

db.runCommand({
   findAndModify: "members",
   query: { "points": { $lte: 20 }, "status": "P" },
   remove: true,
   hint: { status: 1 }
})

To see the index used, run explain on the operation:要查看使用的索引，请对操作运行explain：

db.runCommand(
   {
     explain: {
       findAndModify: "members",
       query: { "points": { $lte: 20 }, "status": "P" },
       remove: true,
       hint: { status: 1 }
     },
     verbosity: "queryPlanner"
   }
)

Use Variables in let在let中使用变量

To define variables that you can access elsewhere in the command, use the let option.要定义可以在命令的其他位置访问的变量，请使用let选项。

Create a collection cakeFlavors:创建集合cakeFlavors：

db.cakeFlavors.insertMany( [
   { _id: 1, flavor: "chocolate" },
   { _id: 2, flavor: "strawberry" },
   { _id: 3, flavor: "cherry" }
] )

The following example defines a targetFlavor variable in let and uses the variable to change the cake flavor from cherry to orange:以下示例在let中定义了一个targetFlavor变量，并使用该变量将蛋糕口味从樱桃更改为橙色：

db.cakeFlavors.runCommand( {
   findAndModify: db.cakeFlavors.getName(),
   query: { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
   update: { flavor: "orange" },
   let: { targetFlavor: "cherry" }
} )