替换文档

在此页面上

Overview

样本数据
替换操作
所需参数
返回值
例子
修改替换操作
例子
更多信息
API 文档

Overview

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

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

样本数据

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

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

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

替换操作

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

所需参数

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

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

返回值

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

方法	说明
`getMatchedCount()`	Returns the number of documents that matched the query filter, regardless of how many were updated.
`getModifiedCount()`	Returns the number of documents modified by the update operation. If an updated document is identical to the original, it is not included in this count.
`getUpsertedCount()`	Returns the number of documents upserted into the database, if any.
`getUpsertedId()`	Returns the ID of the document that was upserted in the database, if the driver performed an upsert.
`isAcknowledged()`	Returns a boolean indicating whether the write operation was acknowledged.

例子

以下示例使用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`	Specifies whether the replace operation performs an upsert operation if no documents match the query filter. For more information, see the upsert statement in the MongoDB Server manual. Defaults to `false`.
`bypassDocumentValidation`	Specifies whether the replace operation bypasses document validation. This lets you replace documents that don't meet the schema validation requirements, if any exist. For more information about schema validation, 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.
`hint`	Gets or sets the index to scan for documents. For more information, see the hint statement in the MongoDB Server manual.
`session`	Specifies the client session to associate with the operation.
`let`	Specifies a document with a list of values to improve operation readability. Values must be constant or closed expressions that don't reference document fields. For more information, see the let statement in the MongoDB Server manual.
`comment`	Attaches a comment to the operation. For more information, see the insert command fields guide in the MongoDB Server manual.

例子

以下代码使用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]
);

Overview

样本数据

替换操作

所需参数

返回值

例子

重要

修改替换操作

例子

更多信息

API 文档