db.collection.findOneAndReplace()

Parameters and Options参数和选项

The findOneAndReplace() method takes the following parameters and options:findOneAndReplace()方法采用以下参数和选项：

collation: {
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

Returns返回值

Returns either the original document or, if returnNewDocument: true, the replacement document.返回原始文档，如果returnNewDocument: true，则返回替换文档。

Document Match文档匹配

db.collection.findOneAndReplace() replaces the first matching document in the collection that matches the filter. 替换集合中与filter匹配的第一个匹配文档。The sort parameter can be used to influence which document is modified.sort参数可用于影响修改的文档。

Projection投影

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

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

Sharded Collections分片集合

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

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

Transactions事务

db.collection.findOneAndReplace() can be used inside multi-document transactions.可以在多文档事务处理中使用。

Replace A Document替换文档

Create a sample scores collection with the following documents:使用以下文档创建示例scores集合：

db.scores.insertMany([
   { "_id" : 1, "team" : "Fearful Mallards", "score" : 25000 },
   { "_id" : 2, "team" : "Tactful Mooses", "score" : 23500 },
   { "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 },
   { "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 },
   { "_id" : 5, "team" : "Garrulous Bears", "score" : 18000 }
]);

The following operation finds a document with score less than 20000 and replaces it:以下操作查找score小于20000的文档并替换它：

db.scores.findOneAndReplace(
   { "score" : { $lt : 20000 } },
   { "team" : "Observant Badgers", "score" : 20000 }
)

The operation returns the original document that has been replaced:该操作返回已替换的原始文档：

{ "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 }

If returnNewDocument was true, the operation would return the replacement document instead.如果returnNewDocument为true，则操作将返回替换文档。

Although multiple documents meet the filter criteria, db.collection.findOneAndReplace() replaces only one document.尽管多个文档符合筛选条件，但db.collection.findOneAndReplace()仅替换一个文档。

Sort and Replace A Document排序和替换文档

Create a sample scores collection with the following documents:使用以下文档创建示例scores集合：

db.scores.insertMany([
   { "_id" : 1, "team" : "Fearful Mallards", "score" : 25000 },
   { "_id" : 2, "team" : "Tactful Mooses", "score" : 23500 },
   { "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 },
   { "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 },
   { "_id" : 5, "team" : "Garrulous Bears", "score" : 18000 }
]);

By including an ascending sort on the score field, the following example replaces the document with the lowest score among those documents that match the filter:通过在score字段中包含升序排序，以下示例将使用与筛选器匹配的文档中得分最低的文档替换该文档：

db.scores.findOneAndReplace(
   { "score" : { $lt : 20000 } },
   { "team" : "Observant Badgers", "score" : 20000 },
   { sort: { "score" : 1 } }
)

The operation returns the original document that has been replaced:该操作返回已替换的原始文档：

{ "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 }

See Replace A Document for the non-sorted result of this command.有关此命令的未排序结果，请参阅替换文档。

Project Specific Fields in Return Document退货单中的项目特定字段

Create a sample scores collection with the following documents:使用以下文档创建示例scores集合：

db.scores.insertMany([
   { "_id" : 1, "team" : "Fearful Mallards", "score" : 25000 },
   { "_id" : 2, "team" : "Tactful Mooses", "score" : 23500 },
   { "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 },
   { "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 },
   { "_id" : 5, "team" : "Garrulous Bears", "score" : 18000 }
])

The following operation uses projection to only display the team field in the returned document:以下操作使用投影仅显示返回文档中的team字段：

db.scores.findOneAndReplace(
   { "score" : { $lt : 22250 } },
   { "team" : "Therapeutic Hamsters", "score" : 22250 },
   { sort : { "score" : 1 }, projection: { "_id" : 0, "team" : 1 } }
)

The operation returns the original document with only the team field:该操作返回仅包含team字段的原始文档：

{ "team" : "Cuddly Zebras" }

Replace Document with Time Limit用时间限制替换文档

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

try {
   db.scores.findOneAndReplace(
      { "score" : { $gt : 25000 } },
      { "team" : "Emphatic Rhinos", "score" : 25010 },
      { 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 }

Replace Document with Upsert用更新内容替换文档

The following operation uses the upsert field to insert the replacement document if no document matches the filter:如果没有与筛选器匹配的文档，则以下操作使用upsert字段插入替换文档：

try {
   db.scores.findOneAndReplace(
      { "team" : "Fortified Lobsters" },
      { "_id" : 6019, "team" : "Fortified Lobsters" , "score" : 32000},
      { upsert : true, returnNewDocument: true }
   );
} catch (e){
   print(e);
}

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

{
   "_id" : 6019,
   "team" : "Fortified Lobsters",
   "score" : 32000
}

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

Create a sample myColl collection with the following documents:使用以下文档创建示例myColl集合：

db.myColl.insertMany([
   { _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.findOneAndReplace(
   { category: "cafe", status: "a" },
   { category: "cafÉ", status: "Replaced" },
   { collation: { locale: "fr", strength: 1 } }
);

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

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