替换文档

本页面

概述

示例数据
替换操作
替换一个文档示例
选项
返回值
附加信息
API 文档

概述

在本指南中，您可以了解如何使用C++驱动程序在MongoDB集合上运行替换操作。替换操作会删除目标文档中除_id字段外的所有字段，并用新的字段替换它们。您可以通过调用replace_one()方法来替换单个文档。_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 服务器手册中的查询过滤器文档。
替换文档：指定要插入新文档中的字段和值。

重要

_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`	指定是否绕过文档验证。当设置为`true`时，这允许您用一个不符合模式验证要求的文档替换文档。有关更多信息，请参阅MongoDB服务器手册中的模式验证。默认为`false`。
`collation`	指定排序结果时使用的语言排序规则类型。有关更多信息，请参阅MongoDB服务器手册中的排序规则。
`comment`	指定要附加到操作的有效BSON类型的注释。一旦设置，此注释将显示在以下位置的此命令记录旁边 mongod日志消息，在`attr.command.cursor.comment`字段数据库分析器输出，在`system.profile.command` `comment`字段 `currentOp`输出，在`currentOp.command` `comment`字段有关更多信息，请参阅MongoDB服务器手册中的插入命令字段指南。
`hint`	指定要扫描以匹配查询筛选器的索引。有关更多信息，请参阅MongoDB服务器手册中的提示字段。
`let`	指定包含变量及其值的文档，这些变量和值用于 `replace_one()` 方法。这允许您通过将变量从操作文本中分离出来来提高代码的可读性。值必须是常数或封闭表达式，不能引用文档字段。有关更多信息，请参阅 MongoDB 服务器手册中的 let 字段。
`upsert`	指定在查询过滤器没有匹配的文档时，替换操作是否执行 upsert 操作。默认为`false`。
`write_concern`	设置操作的写入关注点。有关更多信息，请参阅 MongoDB 服务器手册中的写入关注点。

示例：hint 选项

以下示例使用 create_index() 方法在 name 字段上创建一个升序的单字段索引。然后，它将一个 mongocxx::options::replace 对象传递给 replace_one() 方法，并在将其 hint 字段设置为新的索引后。这指导替换操作在替换具有 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 对象传递给 replace_one() 方法后，将其 upsert 字段值设置为 true。因为没有文档匹配查询过滤器，这指导替换操作在集合中插入一个具有 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 类的实例。此类包含以下成员函数

函数	说明
`matched_count()`	返回匹配查询过滤器的文档数，无论替换了多少个。
`modified_count()`	返回被替换操作修改的文档数。如果替换的文档与原始文档相同，则不包括在此计数中。
`result()`	返回操作的批量写入结果。
`upserted_id()`	返回在数据库中进行了upsert操作的文档的ID。

示例：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() 成员函数以打印 upserted 文档的 _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

概述