替换文档

在本页

概述

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

概述

在此指南中，您可以学习如何使用 MongoDB PHP 库在 MongoDB 集合上执行替换操作。替换操作与更新操作不同。更新操作仅修改目标文档中指定的字段。替换操作会删除目标文档中的所有字段，并用新的字段替换它们。

要替换文档，请使用MongoDB\Collection::replaceOne() 方法。

示例数据

本指南中的示例使用来自 sample_restaurants 数据库中的 restaurants 集合。要访问您的 PHP 应用程序中的此集合，请实例化一个连接到 Atlas 集群的 MongoDB\Client 并将以下值分配给您的 $collection 变量

$collection = $client->sample_restaurants->restaurants;

有关创建免费 MongoDB Atlas 集群并加载数据集的说明，请参阅Atlas 入门指南。

替换操作

您可以使用 MongoDB\Collection::replaceOne() 来执行替换操作。此方法从第一个符合搜索条件的文档中删除所有字段（除了 _id 字段），然后将您指定的字段和值插入到文档中。

必需参数

replaceOne() 方法需要以下参数

查询过滤器 文档，它决定了要替换的文档。有关查询过滤器的更多信息，请参阅 MongoDB 服务器手册中的查询过滤器文档部分。
替换文档，它指定了要插入新文档的字段和值。

返回值

replaceOne() 方法返回一个 MongoDB\UpdateResult 对象。MongoDB\UpdateResult 类型包含以下方法

方法	描述
`getMatchedCount()`	返回与查询过滤器匹配的文档数，无论更新了多少个。
`getModifiedCount()`	返回更新操作修改的文档数。如果一个更新的文档与原始文档相同，则不包括在此计数中。
`getUpsertedCount()`	返回数据库中插入的文档数（如果有）。
`getUpsertedId()`	返回数据库中更新或插入的文档的ID，如果驱动程序执行了更新或插入操作。
`isAcknowledged()`	返回一个布尔值，表示写操作是否被确认。

示例

以下示例使用replaceOne()方法替换字段值，其中name字段的值是'Pizza Town'。然后打印修改的文档数量

$replace_document = [
    'name' => 'Mongo\'s Pizza',
    'cuisine' => 'Pizza',
    'address' => [
        'street' => '123 Pizza St',
        'zipCode' => '10003',
    ],
    'borough' => 'Manhattan'
];
$result = $collection->replaceOne(['name' => 'Pizza Town'], $replace_document);
echo 'Modified documents: ', $result->getModifiedCount();

Modified documents: 1

重要

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

修改替换操作

您可以通过传递一个指定选项值的数组作为参数来修改MongoDB\Collection::replaceOne()方法的行为。以下表格描述了一些可以在数组中设置的选项

选项	描述
`upsert`	指定在查询过滤器没有匹配到任何文档时，替换操作是否执行插入操作。有关更多信息，请参阅MongoDB服务器手册中的upsert语句。默认值为`false`。
`bypassDocumentValidation`	指定替换操作是否绕过文档验证。这允许您替换不符合模式验证要求的文档（如果存在）。有关模式验证的更多信息，请参阅 MongoDB 服务器手册中的模式验证。默认值为`false`。
`排序规则`	指定在排序结果时使用的语言排序规则类型。有关更多信息，请参阅 MongoDB 服务器手册中的排序规则。
`提示`	获取或设置要扫描文档的索引。有关更多信息，请参阅 MongoDB 服务器手册中的提示语句。
`会话`	指定与操作关联的客户端会话。
`let`	指定一个包含值列表的文档，以提高操作的可读性。值必须是常量或无文档字段引用的封闭表达式。有关更多信息，请参阅 MongoDB 服务器手册中的let 语句。
`注释`	将注释附加到操作。有关更多信息，请参阅 MongoDB 服务器手册中的插入命令字段指南。

示例

以下代码使用 replaceOne() 方法查找第一个 name 字段值为 'Food Town' 的文档，然后使用新文档替换该文档，其中 name 的值是 'Food World'。因为 upsert 选项设置为 true，如果查询过滤器与任何现有文档不匹配，则库将插入新文档。

$replace_document = [
    'name' => 'Food World',
    'cuisine' => 'Mixed',
    'address' => [
        'street' => '123 Food St',
        'zipCode' => '10003',
    ],
    'borough' => 'Manhattan'
];
$result = $collection->replaceOne(
    ['name' => 'Food Town'],
    $replace_document,
    ['upsert' => true]
);

概述

示例数据

替换操作

必需参数

返回值

示例

重要

修改替换操作

示例

更多信息

API 文档