findAndModify (database command)（数据库命令）

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. If the query does not match a document to remove, value contains null.对于remove操作，如果查询与文档匹配，则value包含删除的文档。如果查询与要删除的文档不匹配，则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 updated 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使用唯一索引的Upsert

Upserts can create duplicate documents, unless there is a unique index to prevent duplicates.除非有唯一的索引来防止重复，否则Upserts可以创建重复的文档。

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操作都可能导致插入，从而创建多个名为Andy的文档。

A unique index on the name field ensures that only one document is created. With a unique index in place, the multiple findAndModify operations now exhibit the following behavior:name字段上的唯一索引可确保只创建一个文档。有了唯一的索引，多个findAndModify操作现在表现出以下行为：

• Exactly one findAndModify operation will successfully insert a new document.只需执行一次findAndModify操作，即可成功插入新文档。

• Other findAndModify operations either update the newly-inserted document or fail due to a unique key collision.其他findAndModify操作要么更新新插入的文档，要么由于唯一键冲突而失败。

  In order for other findAndModify operations to update the newly-inserted document, all of the following conditions must be met:为了使其他findAndModify操作更新新插入的文档，必须满足以下所有条件：

  • The target collection has a unique index that would cause a duplicate key error.目标集合具有唯一索引，这将导致重复键错误。
  • The update operation is not updateMany or multi is false.更新操作不是updateMany或multi为false。

  • The update match condition is either:更新匹配条件为：

    • A single equality predicate. For example 一个等式谓词。例如{ "fieldA" : "valueA" }
    • A logical AND of equality predicates. For example 等式谓词的逻辑AND。例如{ "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.下表显示了当发生键冲突时，导致更新或失败的upsert操作示例。

{ 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分片化集合

To use findAndModify on a sharded collection:要在分片集合上使用findAndModify，请执行以下操作：

• If you only target one shard, you can use a partial shard key in the query field or,如果你只针对一个分片，你可以在query字段中使用部分分片键，或者，
• You can provide an equality condition on a full shard key in the query field.您可以在query字段中为完整分片键提供相等条件。
• Starting in version 7.1, you do not need to provide the shard key or _id field in the query specification.从7.1版本开始，您不需要在查询规范中提供分片键或_id字段。

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:要针对缺少分片键的文档，您可以将null相等匹配与另一个筛选条件结合使用（例如在_id字段上）。例如：

{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key文档的_id缺少分片键

Schema Validation模式验证

The findAndModify command adds support for the bypassDocumentValidation option, which lets you bypass schema 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. To obtain the updated document, use the new option.默认情况下，findAndModify返回一个对象，其中包含文档的预修改版本以及操作的状态。要获取更新的文档，请使用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 distributed 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.查询在people集合中找到一个文档，其中name字段的值为Tom，state字段的值是active，rating字段的值大于10。
2. The sort orders the results of the query in ascending order. If multiple documents meet the query condition, the command will select for modification the first document as ordered by this sort.sort按升序对查询结果进行排序。如果多个文档符合query条件，则命令将按此排序选择第一个文档进行修改。
3. The update increments the value of the score field by 1.update将score（分数）字段的值 递增1。

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, andlastErrorObject字段，其中包含命令的详细信息，包括字段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 updated 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. Using the shell helper, this previous operation can take the following form:mongosh和许多驱动程序都提供了一个findAndModify()辅助方法。使用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 updated 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命令包含update操作的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, andlastErrorObject字段，其中包含命令的详细信息，包括包含新插入文档的_id值的upserted字段，以及
• The value field containing null.value字段包含null。

{
  "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进行数组更新操作

When updating an array field, you can specify arrayFilters that determine which array elements to update.更新数组字段时，可以指定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使用聚合管道进行更新

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:例如，使用以下文档创建一个集合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" }
} )