db.collection.findAndModify()

fields Projection字段投影

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

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

Upsert with Unique Index具有唯一索引的更新程序

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.在将upsert:true选项与findOneAndUpdate()方法一起使用时，如果不对查询字段使用唯一索引，则具有类似查询字段的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()操作都将更新新插入的文档，并增加score值。

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

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

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. 从MongoDB 4.2开始，db.collection.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.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" }
} )