db.collection.findOneAndUpdate() (mongosh method方法)

Performance演出

Retryable writes require the findOneAndUpdate() method to copy the entire document into a special side collection for each node in a replica set before it performs the update. 可重试写入要求findOneAndUpdate()方法在执行更新之前，将整个文档复制到副本集中每个节点的特殊侧集合中。This can make findOneAndUpdate() an expensive operation when dealing with large documents or large replica sets.这可能会使findOneAndUpdate()在处理大型文档或大型副本集时成为一项昂贵的操作。

Document Match文档匹配

db.collection.findOneAndUpdate() updates the first matching document in the collection that matches the filter. If no document matches the filter, no document is updated.更新集合中与filter匹配的第一个匹配文档。如果没有文档与filter匹配，则不会更新文档。

The sort parameter can be used to influence which document is updated.sort参数可用于影响更新哪个文档。

Projection投影

The projection parameter takes a document in the following form:projection参数采用以下形式的文档：

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

Sharded Collections分片化集合

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字段上）。例如：

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

Transactions事务

db.collection.findOneAndUpdate() can be used inside distributed transactions.可以在分布式事务中使用。

Oplog Entries操作日志条目

If a db.collection.findOneAndUpdate() operation successfully updates a document, the operation adds an entry on the oplog (operations log). 如果db.collection.findOneAndUpdate()操作成功更新了文档，则该操作会在oplog（操作日志）上添加一个条目。If the operation fails or does not find a document to update, the operation does not add an entry on the oplog.如果操作失败或找不到要更新的文档，则操作不会在oplog上添加条目。

Update A Document更新文档

The grades collection contains documents similar to the following:grades集合包含类似于以下内容的文件：

{ _id: 6305, name : "A. MacDyver", "assignment" : 5, "points" : 24 },
{ _id: 6308, name : "B. Batlock", "assignment" : 3, "points" : 22 },
{ _id: 6312, name : "M. Tagnum", "assignment" : 5, "points" : 30 },
{ _id: 6319, name : "R. Stiles", "assignment" : 2, "points" : 12 },
{ _id: 6322, name : "A. MacDyver", "assignment" : 2, "points" : 14 },
{ _id: 6234, name : "R. Stiles", "assignment" : 1, "points" : 10 }

The following operation finds the first document where name : R. Stiles and increments the score by 5:以下操作将找到第一个name : R. Stiles的文档，并将score递增5：

db.grades.findOneAndUpdate(
   { "name" : "R. Stiles" },
   { $inc: { "points" : 5 } }
)

The operation returns the original document before the update:该操作返回更新前的原始文档：

{ _id: 6319, name: "R. Stiles", "assignment" : 2, "points" : 12 }

If returnNewDocument was true, the operation would return the updated document instead.如果returnNewDocument为true，则操作将返回更新的文档。

Sort And Update A Document对文档进行排序和更新

The grades collection contains documents similar to the following:grades集合包含类似于以下内容的文件：

{ _id: 6305, name : "A. MacDyver", "assignment" : 5, "points" : 24 },
{ _id: 6308, name : "B. Batlock", "assignment" : 3, "points" : 22 },
{ _id: 6312, name : "M. Tagnum", "assignment" : 5, "points" : 30 },
{ _id: 6319, name : "R. Stiles", "assignment" : 2, "points" : 12 },
{ _id: 6322, name : "A. MacDyver", "assignment" : 2, "points" : 14 },
{ _id: 6234, name : "R. Stiles", "assignment" : 1, "points" : 10 }

The following operation updates a document where name : "A. MacDyver". The operation sorts the matching documents by points ascending to update the matching document with the least points.以下操作将更新name : "A. MacDyver"的文档。该操作按points升序对匹配文档进行排序，以用最少的点更新匹配文档。

db.grades.findOneAndUpdate(
   { "name" : "A. MacDyver" },
   { $inc : { "points" : 5 } },
   { sort : { "points" : 1 } }
)

The operation returns the original document before the update:该操作返回更新前的原始文档：

{ _id: 6322, name: "A. MacDyver", "assignment" : 2, "points" : 14 }

Project the Returned Document投影退回的文档

The following operation uses projection to only display the _id, points, and assignment fields in the returned document:以下操作使用投影仅显示返回文档中的_id、points和assignment字段：

db.grades.findOneAndUpdate(
   { "name" : "A. MacDyver" },
   { $inc : { "points" : 5 } },
   { sort : { "points" : 1 }, projection: { "assignment" : 1, "points" : 1 } }
)

The operation returns the original document with only the fields specified in the projection document and the _id field as it was not explicitly suppressed (_id: 0) in the projection document.该操作返回原始文档，其中仅包含projection文档中指定的字段和_id字段，因为它在投影文档中没有被明确抑制（_id:0）。

{ "_id" : 6322, "assignment" : 2, "points" : 14 }

Update Document with Time Limit按时间限制更新文档

The following operation sets a 5ms time limit to complete the update:以下操作设置了5ms的时间限制来完成更新：

try {
   db.grades.findOneAndUpdate(
      { "name" : "A. MacDyver" },
      { $inc : { "points" : 5 } },
      { sort: { "points" : 1 }, maxTimeMS : 5 };
   );
}
catch(e){
   print(e);
}

If the operation exceeds the time limit, it returns:如果操作超过时间限制，则返回：

Error: findAndModifyFailed failed: { "ok" : 0, "errmsg" : "operation exceeded time limit", "code" : 50 }

Update Document with Upsert使用Upsert更新文档

The following operation uses the upsert field to insert the update document if nothing matches the filter:如果没有与筛选器匹配的内容，以下操作将使用upsert字段插入更新文档：

try {
db.grades.findOneAndUpdate(
   { "name" : "A.B. Abracus" },
   { $set: { "name" : "A.B. Abracus", "assignment" : 5}, $inc : { "points" : 5 } },
   { sort: { "points" : 1 }, upsert:true, returnNewDocument : true }
);
}
catch (e){
   print(e);
}

The operation returns the following:该操作返回以下内容：

{
   "_id" : ObjectId("5789249f1c49e39a8adc479a"),
   "name" : "A.B. Abracus",
   "assignment" : 5,
   "points" : 5
}

If returnNewDocument was false, the operation would return null as there is no original document to return.如果returnNewDocument为false，则操作将返回null，因为没有要返回的原始文档。

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:以下操作包括排序规则选项：

db.myColl.findOneAndUpdate(
   { category: "cafe" },
   { $set: { status: "Updated" } },
   { collation: { locale: "fr", strength: 1 } }
);

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

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

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.students.findOneAndUpdate(
   { grades: { $gte: 100 } },
   { $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.findOneAndUpdate(
   { _id : 1 },
   { $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使用聚合管道进行更新

db.collection.findOneAndUpdate() 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.students2.findOneAndUpdate(
   { _id : 1 },
   [ { $set: { "total" : { $sum: "$grades.grade" } } } ],  // The $set stage is an alias for ``$addFields`` stage
   { returnNewDocument: 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
}