替换文档

在此页面上

Overview

样本数据
替换操作
替换一个文档示例
选项
返回值
更多信息
API 文档

Overview

在本指南中，您可以学习；了解如何使用C++驾驶员对MongoDB集合运行替换操作。替换操作会删除目标文档中除 _id字段之外的所有字段，并替换为新字段。您可以调用 replace_one() 方法来替换单个文档。

样本数据

本指南中的示例使用 Atlas示例数据集的sample_restaurants数据库中的restaurants集合。要从C++应用程序访问权限此集合，请实例化一个连接到Atlas 集群的mongocxx::client ，并将以下值分配给db和collection变量：

auto db = client["sample_restaurants"];
auto collection = db["restaurants"];

要学习；了解如何创建免费的MongoDB Atlas 群集并加载示例数据集，请参阅Atlas入门指南。

替换操作

您可以通过调用 replace_one() 方法来执行替换操作。此方法会从匹配搜索条件的第一个文档中删除除 _id字段之外的所有字段。然后，它将您指定的字段和值插入到文档中。

replace_one() 方法需要使用以下参数：

查询过滤文档：指定要替换的文档。有关查询筛选器的更多信息，请参阅MongoDB Server手册中的查询筛选器文档。
替换文档：指定要在新文档中插入的字段和值。

重要

_id 字段的值不可变。如果您的替换文档指定 _id 字段的值，则它必须与现有文档的 _id 值匹配。

替换一个文档示例

以下示例使用 replace_one() 方法将 name字段值为 "Nobu" 的文档替换为 name字段值为 "La Bernadin" 的新文档：

auto query_filter = make_document(kvp("name", "Nobu"));
auto replace_doc = make_document(kvp("name", "La Bernadin"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view());

要检查是否成功替换了文档，可以使用 find_one() 方法打印出新文档：

auto new_doc = collection.find_one(make_document(kvp("name", "La Bernadin")));
std::cout << "New document: " << bsoncxx::to_json(*new_doc) << std::endl;

New document: { "_id" : { "$oid" : "..." }, "name" : "La Bernadin" }

要学习；了解有关find_one()方法的更多信息，请参阅《检索数据》指南中的查找一个文档。

选项

您可以通过将 mongocxx::options::replace 类的实例作为可选参数传递来修改 replace_one() 方法的行为。下表描述了您可以在 mongocxx::options::replace实例中设立的字段：

字段	说明
`bypass_document_validation`	Specifies whether the replace operation bypasses document validation. When set to `true`, this lets you replace a document with a new document that doesn't meet the schema validation requirements. For more information, see Schema Validation in the MongoDB Server manual. Defaults to `false`.
`collation`	Specifies the kind of language collation to use when sorting results. For more information, see Collation in the MongoDB Server manual.
`comment`	Specifies a comment of any valid BSON type to attach to the operation. Once set, this comment appears alongside records of this command in the following locations: mongod日志消息，位于 `attr.command.cursor.comment`字段字段中的数据库分析器输出 `system.profile.commandcomment` `currentOp`输出，在`currentOp.commandcomment` 字段 For more information, see the insert Command Fields guide in the MongoDB Server manual.
`hint`	Specifies the index to scan for documents that match the query filter. For more information, see the hint field in the MongoDB Server manual.
`let`	Specifies a document containing variables and their values to be used in the `replace_one()` method. This allows you to improve code readability by separating the variables from the operation text. Values must be constant or closed expressions that don't reference document fields. For more information, see the let field in the MongoDB Server manual.
`upsert`	Specifies whether the replace operation performs an upsert operation if no documents match the query filter. Defaults to `false`.
`write_concern`	Sets the write concern for the operation. For more information, see Write Concern in the MongoDB Server manual.

示例：提示选项

以下示例使用 create_index() 方法在 name字段上创建升序单字段索引。然后，将 hint字段设置为新索引后，将 mongocxx::options::replace对象传递给 replace_one() 方法。这指示替换操作在替换 name字段值为 "Nobu" 的文档时搜索name字段索引：

auto index_specification = make_document(kvp("name", 1));
collection.create_index(index_specification.view());
mongocxx::options::replace opts{}; 
opts.hint(mongocxx::hint{"name_1"});
auto query_filter = make_document(kvp("name", "Nobu"));
auto replace_doc = make_document(kvp("name", "La Bernadin"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view(), opts);

要学习；了解有关索引的更多信息，请参阅《使用索引优化查询》指南。

示例：更新或插入（upsert）选项

以下示例将 mongocxx::options::replace对象的 upsert字段值设置为 true 后，将其传递给 replace_one() 方法。由于没有与查询过滤匹配的文档，因此这会指示替换操作将 name字段值为 "Shake Shack" 的新文档插入到集合中：

std::cout << "Total document count before replace_one(): " << collection.count_documents({}) << std::endl;
mongocxx::options::replace opts{}; 
opts.upsert(true);
auto query_filter = make_document(kvp("name", "In-N-Out Burger"));
auto replace_doc = make_document(kvp("name", "Shake Shack"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view(), opts);
std::cout << "Total document count after replace_one(): " << collection.count_documents({}) << std::endl;

Total document count before replace_one(): 25359
Total document count after replace_one(): 25360

返回值

replace_one() 方法返回 mongocxx::result::replace 类的实例。该类包含以下成员函数：

function	说明
`matched_count()`	Returns the number of documents that matched the query filter, regardless of how many were replaced.
`modified_count()`	Returns number of documents modified by the replace operation. If a replaced document is identical to the original, it is not included in this count.
`result()`	Returns the bulk write result for the operation.
`upserted_id()`	Returns the ID of the document that was upserted in the database, if the driver performed an upsert.

示例：matched_count()

以下示例使用 replace_one() 方法将 name字段值为 "Shake Shack" 的文档替换为 name字段值为 "In-N-Out Burger" 的新文档。然后，它调用 matched_count() 成员函数来打印与查询过滤匹配的文档数量：

auto query_filter = make_document(kvp("name", "Shake Shack"));
auto replace_doc = make_document(kvp("name", "In-N-Out Burger"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view());
std::cout << "Matched documents: " << result->matched_count() << std::endl;

Matched documents: 11

示例：upserted_id()

以下示例使用 replace_one() 方法替换 name字段值为 "In-N-Out Burger" 的文档。由于 upsert 选项设立为 true ，因此当查询过滤与任何现有文档都不匹配时， C++驾驶员会插入一个新文档。然后，代码调用 upserted_id() 成员函数来打印已更新或插入的文档的 _id字段值：

mongocxx::options::replace opts{}; 
opts.upsert(true);
auto query_filter = make_document(kvp("name", "In-N-Out Burger"));
auto replace_doc = make_document(kvp("name", "Shake Shack"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view(), opts);
auto id = result->upserted_id()->get_value();
        
std::cout << "Upserted ID: " << id.get_oid().value.to_string() << std::endl;

// Your ID value may differ
Upserted ID: 67128c5ecc1f8c15ea26fcf8