db.collection.findAndModify()

fields Projection投影

The fields option takes a document in the following form:fields选项采用以下形式的文档：

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

Upsert with Unique Index使用唯一索引upsert

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

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.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.如果所有findOneAndUpdate()操作都在任何客户端成功插入数据之前完成了查询阶段，并且name字段上没有唯一索引，则每个findOneAndUpdate()操作可能会导致插入，从而创建多个name: Andy的文档。

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

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

• Exactly one findOneAndUpdate() operation will successfully insert a new document.只需执行一次findOneAndUpdate()操作即可成功插入新文档。
• All other findOneAndUpdate() operations will update the newly-inserted document, incrementing the score value.所有其他findOneAndUpdate()操作都将更新新插入的文档，从而增加分值。

Sharded Collections分片集合

When using findAndModify against a sharded collection, the query must contain an equality condition on shard key.对分片集合使用findAndModify时，query必须包含分片键上的相等条件。

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 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.db.collection.findAndModify()方法添加了对bypassDocumentValidation选项的支持，该选项允许您在使用验证规则插入或更新集合中的文档时绕过文档验证。

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

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

• 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.如果有多个文档符合更新条件，那么对于db.collection.findAndModify()，可以指定一个排序来控制要更新的文档。

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

• By default, db.collection.findAndModify() returns the pre-modified version of the document. 默认情况下，db.collection.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. However, other updates may have modified the document between your update and the document retrieval. 要返回更新后的文档，请使用find()方法。但是，在您的更新和文档检索之间，其他更新可能已经修改了文档。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 updateOne() method atomically update the document. See Atomicity and Transactions for more details about interactions and order of operations of these methods.修改单个文档时，db.collection.findAndModify()和updateOne()方法都会自动更新文档。有关这些方法的交互和操作顺序的更多详细信息，请参阅原子性和事务。

Transactions事务

db.collection.findAndModify() can be used inside multi-document 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.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 method will select for modification the first document as ordered by this sort.如果多个文档满足query条件，则该方法将选择按此sort的第一个文档进行修改。
3. The update increments the value of the score field by 1.更新会将score字段的值增加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 modified document, add the new:true option to the method.要返回修改后的文档，请将new:true选项添加到方法中。

   If no document matched the query condition, the method returns null.如果没有与query条件匹配的文档，则该方法返回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:以下方法包括更新操作的upsert:true选项，用于update匹配的文档，或者如果不存在匹配的文档则创建新文档：

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:如果该方法找不到匹配的文档，则该方法将创建一个新文档。由于该方法包含sort选项，因此它返回一个空文档{ }作为原始（修改前）文档：

{ }

If the method did not include a sort option, the method returns null.如果该方法不包括sort选项，则该方法将返回null。

null

Return New Document返回新文档

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

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

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

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.collation允许用户为字符串比较指定特定于语言的规则，例如大小写和重音标记的规则。

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.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为数组更新操作指定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.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.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.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:从MongoDB 4.2开始，db.collection.findAndModify()可以接受更新的聚合管道。管道可由以下阶段组成：

• $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.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
}

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.findAndModify( {
   query: {
      $expr: { $eq: [ "$flavor", "$$targetFlavor" ] }
   },
   update: { flavor: "orange" },
   let: { targetFlavor: "cherry" }
} )

User Roles and Document Updates用户角色和文档更新

Starting in MongoDB 7.0, you can use the new USER_ROLES system variable to return user roles.从MongoDB 7.0开始，您可以使用新的USER_ROLES系统变量来返回用户角色。

The example in this section shows updates to fields in a collection containing medical information. 本节中的示例显示了对包含医疗信息的集合中的字段的更新。The example reads the current user roles from the USER_ROLES system variable and only performs the updates if the user has a specific role.此示例从USER_ROLES系统变量中读取当前用户角色，并且仅当用户具有特定角色时才执行更新。

To use a system variable, add $$ to the start of the variable name. Specify the USER_ROLES system variable as $$USER_ROLES.要使用系统变量，请在变量名的开头添加$$。将USER_ROLES系统变量指定为$$USER_ROLES。

The example creates these users:该示例创建了以下用户：

• James with a Billing role.具有Billing角色的James
• Michelle with a Provider role.具有Provider角色的Michelle

Perform the following steps to create the roles, users, and collection:执行以下步骤以创建角色、用户和集合：

db.createRole( { role: "Billing", privileges: [ { resource: { db: "test",
   collection: "medicalView" }, actions: [ "find" ] } ], roles: [ ] } )
db.createRole( { role: "Provider", privileges: [ { resource: { db: "test",
   collection: "medicalView" }, actions: [ "find" ] } ], roles: [ ] } )

db.createUser( {
   user: "James",
   pwd: "js008",
   roles: [
      { role: "Billing", db: "test" }
   ]
} )

db.createUser( {
   user: "Michelle",
   pwd: "me009",
   roles: [
      { role: "Provider", db: "test" }
   ]
} )

db.medical.insertMany( [
   {
      _id: 0,
      patientName: "Jack Jones",
      diagnosisCode: "CAS 17",
      creditCard: "1234-5678-9012-3456"
   },
   {
      _id: 1,
      patientName: "Mary Smith",
      diagnosisCode: "ACH 01",
      creditCard: "6541-7534-9637-3456"
   }
] )

Log in as as Michelle, who has the Provider role, and perform an update:以Michelle的身份登录，Michelle具有Provider角色，并执行更新：

db.auth( "Michelle", "me009" )

// Attempt to find and modify document尝试查找和修改文档
db.medical.findAndModify( {
   query:
      { $and: [
         {
            // Only update the document for Mary Smith仅为Mary Smith更新文档
            patientName: { $eq: "Mary Smith" }
         },
         {
            // User must have the Provider role to perform the update用户必须具有提供Provider才能执行更新
            $expr: { $ne: [ {
               $setIntersection: [ [ "Provider" ], "$$USER_ROLES.role" ]
            }, [] ] }
         }
      ]
   },
   // Update document更新文档
   update: {
      patientName: "Mary Smith",
      diagnosisCode: "ACH 03",
      creditCard: "6541-7534-9637-3456"
   }
} )

The previous example uses $setIntersection to return documents where the intersection between the "Provider" string and the user roles from $$USER_ROLES.role is not empty. 上一个示例使用$setIntersection返回"Provider"字符串与$$USER_ROLES.role中的用户角色之间的交集不为空的文档。Michelle has the Provider role, so the update is performed.Michelle具有Provider角色，因此执行更新。

Next, log in as as James, who does not have the Provider role, and attempt to perform the same update:接下来，以James的身份登录，James没有Provider角色，并尝试执行相同的更新：

db.auth( "James", "js008" )

// Attempt to find and modify document尝试查找和修改文档
db.medical.findAndModify( {
   query:
      { $and: [
         {
            // Only update the document for Mary Smith仅为Mary Smith更新文档
            patientName: { $eq: "Mary Smith" }
         },
         {
            // User must have the Provider role to perform the update用户必须具有Provider角色才能执行更新
            $expr: { $ne: [ {
               $setIntersection: [ [ "Provider" ], "$$USER_ROLES.role" ]
            }, [] ] }
         }
      ]
   },
   // Update document更新文档
   update: {
      patientName: "Mary Smith",
      diagnosisCode: "ACH 03",
      creditCard: "6541-7534-9637-3456"
   }
} )

The previous example does not update any documents.上一个示例不更新任何文档。