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

upsert

If upsert: true and no documents match the filter, db.collection.replaceOne() creates a new document based on the replacement document.如果upsert: true且没有文档与filter匹配，db.collection.replaceOne()将根据replacement文档创建一个新文档。

If you specify upsert: true on a sharded collection, you must include the full shard key in the filter. 如果在分片集合上指定upsert: true，则必须在filter中包含完整的分片键。For additional db.collection.replaceOne() behavior on a sharded collection, see Sharded Collections.有关分片集合上的其他db.collection.replaceOne()行为，请参阅分片集合。

See Replace with Upsert.请参阅用Upsert替换。

Capped Collections封顶集合

If a replacement operation changes the document size, the operation will fail.如果替换操作更改了文档大小，则操作将失败。

Time Series Collections时间序列集合

You cannot use the replaceOne() method on a time series collection.您不能在时间序列集合上使用replaceOne()方法。

Sharded Collections分片化集合

db.collection.replaceOne() attempts to target a single shard, first by using the query filter. If the operation cannot target a single shard by the query filter, it then attempts to target by the replacement document.尝试首先使用查询筛选器来定位单个分片。如果操作无法通过查询筛选器定位单个分片，则它会尝试通过替换文档定位。

In earlier versions, the operation attempts to target using the replacement document.在早期版本中，该操作尝试使用替换文档作为目标。

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

Transactions事务

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

Replace替换

The restaurant collection contains the following documents:restaurant集合包含以下文件：

db.restaurant.insertMany ( [
   { _id: 1, name: "Central Perk Cafe", Borough: "Manhattan" },
   { _id: 2, name: "Rock A Feller Bar and Grill", Borough: "Queens", violations: 2 },
   { _id: 3, name: "Empire State Pub", Borough: "Brooklyn", violations: 0 }
] )

The following operation replaces a single document where name: "Central Perk Cafe":以下操作将替name: "Central Perk Cafe"的单个文档：

try {
   db.restaurant.replaceOne(
      { "name" : "Central Perk Cafe" },
      { "name" : "Central Pork Cafe", "Borough" : "Manhattan" }
   );
} catch (e){
   print(e);
}

The operation returns:操作返回：

{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

If no matches were found, the operation instead returns:如果没有找到匹配项，则操作将返回：

{ "acknowledged" : true, "matchedCount" : 0, "modifiedCount" : 0 }

Setting upsert: true would insert the document if no match was found. See Replace with Upsert如果未找到匹配项，设置upsert: true将插入文档。请参阅更换为Upsert。

Replace with Upsert替换为Upsert

The restaurant collection contains the following documents:restaurant集合包含以下文件：

db.restaurant.insertMany( [
   { _id: 1, name: "Central Perk Cafe", Borough: "Manhattan",  violations: 3 },
   { _id: 2, name: "Rock A Feller Bar and Grill", Borough: "Queens", violations: 2 },
   { _id: 3, name: "Empire State Pub", Borough: "Brooklyn", violations: 0 }
] )

The following operation attempts to replace the document with name : "Pizza Rat's Pizzaria", with upsert : true:以下操作尝试将文档替换为name : "Pizza Rat's Pizzaria"，并使用upsert : true：

try {
   db.restaurant.replaceOne(
      { "name" : "Pizza Rat's Pizzaria" },
      { "_id": 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "violations" : 8 },
      { upsert: true }
   );
} catch (e){
   print(e);
}

Since upsert : true the document is inserted based on the replacement document. The operation returns:由于upsert:true，文档将根据replacement文档插入。操作返回：

{
   "acknowledged" : true,
   "matchedCount" : 0,
   "modifiedCount" : 0,
   "upsertedId" : 4
}

The collection now contains the following documents:该集合现在包含以下文档：

{ _id: 1, name: "Central Perk Cafe", Borough: "Manhattan", violations: 3 },
{ _id: 2, name: "Rock A Feller Bar and Grill", Borough: "Queens", violations: 2 },
{ _id: 3, name: "Empire State Pub", Borough: "Brooklyn", violations: 0 },
{ _id: 4, name: "Pizza Rat's Pizzaria", Borough: "Manhattan", violations: 8 }

Replace with Write Concern替换为写入关注

Given a three member replica set, the following operation specifies a w of majority and wtimeout of 100:给定一个由三个成员组成的副本集，以下操作指定w为majority，wtimeout为100：

try {
   db.restaurant.replaceOne(
       { "name" : "Pizza Rat's Pizzaria" },
       { "name" : "Pizza Rat's Pub", "Borough" : "Manhattan", "violations" : 3 },
       { w: "majority", wtimeout: 100 }
   );
} catch (e) {
   print(e);
}

If the acknowledgment takes longer than the wtimeout limit, the following exception is thrown:如果确认时间超过wtimeout限制，则抛出以下异常：

WriteConcernError({
   "code" : 64,
   "errmsg" : "waiting for replication timed out",
   "errInfo" : {
     "wtimeout" : true,
     "writeConcern" : {
       "w" : "majority",
       "wtimeout" : 100,
       "provenance" : "getLastErrorDefaults"
     }
   }
})

The following table explains the possible values of errInfo.writeConcern.provenance:下表解释了errInfo.writeConcern.provenance的可能值：

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:

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

db.myColl.replaceOne(
   { category: "cafe", status: "a" },
   { category: "cafÉ", status: "Replaced" },
   { collation: { locale: "fr", strength: 1 } }

);

Specify hint for replaceOne指定replaceOne的hint

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

db.members.insertMany( [
   { _id: 1, member: "abc123", status: "P", points:  0,  misc1: null, misc2: null },
   { _id: 2, member: "xyz123", status: "A", points: 60,  misc1: "reminder: ping me at 100pts", misc2: "Some random comment" },
   { _id: 3, member: "lmn123", status: "P", points:  0,  misc1: null, misc2: null },
   { _id: 4, member: "pqr123", status: "D", points: 20,  misc1: "Deactivated", misc2: null },
   { _id: 5, member: "ijk123", status: "P", points:  0,  misc1: null, misc2: null },
   { _id: 6, member: "cde123", status: "A", points: 86,  misc1: "reminder: ping me at 100pts", misc2: "Some random comment" }
] )

Create the following indexes on the collection:在集合上创建以下索引：

db.members.createIndex( { status: 1 } )
db.members.createIndex( { points: 1 } )

The following update operation explicitly hints to use the index { status: 1 }:以下更新操作明确提示使用索引{ status: 1 }：

db.members.replaceOne(
   { "points": { $lte: 20 }, "status": "P" },
   { "misc1": "using index on status", status: "P", member: "replacement", points: "20"},
   { hint: { status: 1 } }
)

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

{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

To view the indexes used, you can use the $indexStats pipeline:要查看使用的索引，可以使用$indexStats管道：

db.members.aggregate( [ { $indexStats: { } }, { $sort: { name: 1 } } ] )

Replace One Document and Use a Sort替换一个文档并使用排序

Create the following restaurantsSort collection:创建以下restaurantsSort集合：

db.restaurantsSort.insertMany( [
   { _id: 1, name: "Pizza Place", rating: 4, violations: 2 },
   { _id: 2, name: "Burger Joint", rating: 3, violations: 5 },
   { _id: 3, name: "Taco Shop", rating: 4, violations: 1 }
] )

The following example replaces "Pizza Place" with "Clean Eats":以下示例将"Pizza Place"替换为"Clean Eats"：

db.restaurantsSort.replaceOne(
   // Find restaurants with a rating of 4
   { rating: 4 },

   // Replace the found restaurant with Clean Eats
   { name: "Clean Eats", rating: 4, violations: 2 },

   // Sort restaurants found by the most violations with a descending sort
   { sort: { violations: -1 } }
)

The example:示例：

• Finds restaurants with a rating of 4, which are "Pizza Place" and "Taco Shop".查找rating为4的餐厅，分别是"Pizza Place"和"Taco Shop"。
• Sorts the found restaurants by violations in descending order, which places "Pizza Place" in the first position.按violations（违规行为）降序排列找到的餐厅，将"Pizza Place"放在第一位。
• Replaces "Pizza Place" with "Clean Eats".将"Pizza Place"替换为"Clean Eats"。

The following query returns the restaurants:以下查询返回餐厅：

db.restaurantsSort.find()

Output shows "Pizza Place" was replaced with "Clean Eats":输出显示"Pizza Place"被替换为"Clean Eats"：

[
   { _id: 1, name: 'Clean Eats', rating: 4, violations: 2 },
   { _id: 2, name: 'Burger Joint', rating: 3, violations: 5 },
   { _id: 3, name: 'Taco Shop', rating: 4, violations: 1 }
]