/ /

替换文档

Overview

在本指南中，您可以学习；了解如何使用MongoDB PHP库对MongoDB集合运行替换操作。替换操作的执行方式与更新操作不同。更新操作仅修改目标文档中的指定字段。替换操作会删除目标文档中的所有字段，然后替换为新字段。

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

样本数据

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

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

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

替换操作

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

所需参数

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

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

返回值

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

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

例子

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

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

Modified documents: 1

重要

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

修改替换操作

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

选项	说明
`upsert`	指定如果没有文档与查询筛选条件匹配，替换操作是否执行更新或插入（upsert）操作。有关详细信息，请参阅 MongoDB Server 手册中的更新或插入（upsert）声明。默认为 `false`。
`bypassDocumentValidation`	指定替换操作是否绕过文档验证。这使您可以替换不满足模式验证要求的文档（如存在）。有关模式验证的详细信息，请参阅 MongoDB Server 手册中的模式验证。默认为 `false`。
`sort`	指定在执行替换操作之前应用于文档的排序顺序。
`collation`	指定在排序结果时使用的语言排序规则类型。要了解更多信息，请参阅本页面的排序规则部分。
`hint`	获取或设置用于扫描文档的索引。有关更多信息，请参阅 MongoDB Server 手册中的提示语句。
`session`	指定与操作关联的客户端会话。
`let`	指定包含值列表的文档，以提高操作的可读性。值必须是常量或不引用文档字段的闭合表达式。有关更多信息，请参阅MongoDB Server手册中的 let声明。
`comment`	为操作附加注释。有关更多信息，请参阅MongoDB Server手册中的插入命令字段指南。

排序规则

要为操作指定排序规则，请传递 $options大量参数，该参数将 collation 选项设置为操作方法。将 collation 选项分配给配置排序规则规则的大量。

下表描述了可以设立以配置排序规则的字段：

字段	说明
`locale`	(必选) 指定国际单字符组件 (ICU) 区域设置。有关支持的区域设置列表，请参阅 MongoDB Server 手册中的排序规则区域设置和默认参数。数据类型: `string`
`caseLevel`	（可选）指定是否包含大小写比较。当设置为`true` 时，比较行为取决于`strength` 字段的值： - 如果`strength` 为，则`1` PHP 库比较基本字符和大小写。 - 如果`strength` 为`2` ，则 PHP 库比较基本字符、变音符、其他从节点差异和大小写。 - 如果`strength` 为任何其他值，则忽略此字段。当设置为 `false` 时，PHP 库不包含强度级别 `1` 或 `2` 的大小写比较。数据类型：`bool` 默认值：`false`
`caseFirst`	（可选）指定三级比较期间大小写差异的排序顺序。数据类型：`string` 默认：`"off"`
`strength`	(可选) 指定要执行的比较级别，如 ICU 文档中所定义。数据类型：`int` 默认：`3`
`numericOrdering`	（可选）指定驱动程序是将数字字符串作为数字还是字符串进行比较。如果设置为 `true`，PHP 库将数字字符串作为数字进行比较。示例：在比较字符串 "10" 和 "2" 时，该库使用字符串的数字值，并将 "10" 视为大于 "2"。如果设置为 `false`，PHP 库将数字字符串作为字符串进行比较。示例，在比较字符串 "10" 和 "2" 时，该库会一次比较一个字符，并将 "10" 视为小于 "2"。有关更多信息，请参阅MongoDB Server手册中的排序规则限制。数据类型：`bool` 默认：`false`
`alternate`	（可选）指定库是否将空格和标点视为基本字符以进行比较。数据类型：`string` 默认：`"non-ignorable"`
`maxVariable`	（可选）指定当 `alternate` 字段设置为 `"shifted"` 时，库认为可忽略的字符。数据类型：`string` 默认值：`"punct"`
`backwards`	（可选）指定包含变音符号的字符串是否从字符串的后部到前部排序。数据类型：`bool` 默认：`false`

要学习；了解有关排序规则和每个字段可能值的更多信息，请参阅MongoDB Server手册中的排序规则条目。

例子

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

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