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

Fields and Options字段和选项

The findOneAndReplace() method takes the following fields and options:findOneAndReplace()方法接受以下字段和选项：

{ w: <value>, j: <boolean>, wtimeout: <number> }

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

Returns值

Returns the original document by default. Returns the updated document if returnDocument is set to after or returnNewDocument is set to true.默认情况下返回原始文档。如果returnDocument设置为after或returnDocument设置为true，则返回更新的文档。

Document Match文档匹配

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

Projection投影

The projection field 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.findOneAndReplace() can be used inside distributed transactions.可以在分布式事务中使用。

Oplog Entries操作日志条目

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

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字段中包含升序排序，以下示例将替换与filter匹配的文档中分数最低的文档：

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:以下操作使用projection仅显示返回文档中的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用Upert替换文档

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

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

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

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

If returnDocument: "before" was set, the operation would return null because there is no original document to return.如果设置了returnDocument: "before"，则操作将返回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" }