替换文档

本页内容

概述

示例数据
替换操作
必需参数
示例
修改替换操作
替换选项示例
附加信息
API 文档

概述

在本指南中，您可以了解如何使用 C 驱动程序在 MongoDB 集合上执行 替换操作。替换操作与更新操作不同。更新操作仅修改目标文档中指定的字段。替换操作会删除目标文档中的所有字段，并用新字段替换。

要替换文档，请使用mongoc_collection_replace_one() 函数。

示例数据

本指南中的示例使用来自 Atlas 示例数据集的 sample_restaurants 数据库中的 restaurants 集合。要了解如何创建免费的 MongoDB Atlas 集群并加载示例数据集，请参阅 Atlas 入门指南。

替换操作

您可以使用 mongoc_collection_replace_one() 函数执行替换操作。此函数从符合搜索条件的第一个文档中移除所有字段（除了 _id 字段），然后将您指定的字段和值插入到文档中。

必需参数

mongoc_collection_replace_one() 函数需要以下参数

集合：指定要执行替换操作的集合。
查询过滤器文档：指定要匹配的集合文档。函数选择第一个匹配的文档进行替换。有关查询过滤器的更多信息，请参阅 MongoDB 服务器手册中的查询过滤器文档部分。
替换文档：指定要插入到新文档中的字段和值。
选项文档：指定用于自定义操作的选项，或 NULL。
结果位置：指定一个指向可覆盖的存储的指针，该存储将包含操作结果，或 NULL。
错误位置：指定一个错误值的位置，或 NULL。

示例

以下示例使用 mongoc_collection_replace_one() 函数来替换具有 "Pizza Town" 的 name 字段值的文档的字段和值，将其替换为具有 "Mongo's Pizza" 的 name 字段值的文档。

bson_t *query = BCON_NEW ("name", "Pizza Town");
bson_t *replace = BCON_NEW (
    "name", "Mongo's Pizza",
    "cuisine", "Pizza",
    "address", "{",
    "street", "123 Pizza St",
    "zipCode", "10003",
    "}",
    "borough", "Manhattan"
);
bson_error_t error;
if (!mongoc_collection_replace_one (collection, query, replace, NULL, NULL, &error)) {
    fprintf (stderr, "Replace operation failed: %s\n", error.message);
}
bson_destroy (query);
bson_destroy (replace);

重要

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

修改替换操作

您可以通过传递一个指定选项值的BSON文档来修改 mongoc_collection_replace_one() 函数的行为。以下表格描述了您可以在文档中设置的一些选项

选项	描述
`upsert`	指定如果查询过滤器没有匹配的文档，则替换操作是否执行upsert操作。有关更多信息，请参阅MongoDB服务器手册中的upsert语句。默认值为 `false`。
`bypassDocumentValidation`	指定替换操作是否绕过文档验证。这允许您替换不符合模式验证要求的文档（如果存在）。有关模式验证的更多信息，请参阅MongoDB服务器手册中的模式验证。默认值为 `false`。
`collation`	指定比较文本时要使用的语言排序规则类型。有关更多信息，请参阅MongoDB服务器手册中的排序规则。
`hint`	获取或设置用于扫描文档的索引。有关更多信息，请参阅MongoDB服务器手册中的hint语句。
`comment`	将注释附加到操作。有关更多信息，请参阅MongoDB服务器手册中的插入命令字段指南。

替换选项示例

以下代码使用 mongoc_collection_replace_one() 函数查找第一个 name 字段值为 "Food Town" 的文档，然后用一个新文档替换该文档，其中 name 的值为 "Food World"。因为 upsert 选项设置为 true，如果查询过滤器不匹配任何现有文档，则驱动程序将插入一个新文档。

bson_t *query = BCON_NEW ("name", "Food Town");
bson_t *replace = BCON_NEW (
    "name", "Food World",
    "cuisine", "Mixed",
    "address", "{",
    "street", "123 Food St",
    "zipCode", "10003",
    "}",
    "borough", "Manhattan"
);
bson_error_t error;
bson_t opts;
bson_init (&opts);
bson_append_bool (&opts, "upsert", -1, true);
if (!mongoc_collection_replace_one (collection, query, replace, &opts, NULL, &error)) {
    fprintf (stderr, "Replace operation failed: %s\n", error.message);
} 
bson_destroy (query);
bson_destroy (replace);
bson_destroy (&opts);

概述

示例数据

替换操作

必需参数

示例

重要

修改替换操作

替换选项示例

更多信息

API 文档