/ /

批量写入操作

Overview

在本指南中，您可以学习；了解如何使用批量写入操作在单个数据库调用中执行多个写入操作。

考虑这样一种情况：您想要将一个文档插入到一个集合中，更新多个其他文档，然后删除一个文档。如果使用单独的方法，则每个操作都需要调用自己的数据库。相反，您可以使用批量操作来减少对数据库的调用次数。

样本数据

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

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

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

批量操作

要运行批量写入操作，请将写入操作大量传递给MongoDB\Collection::bulkWrite()方法。使用以下语法指定写入操作：

[
    [ 'deleteMany' => [ $filter ] ],
    [ 'deleteOne'  => [ $filter ] ],
    [ 'insertOne'  => [ $document ] ],
    [ 'replaceOne' => [ $filter, $replacement, $options ] ],
    [ 'updateMany' => [ $filter, $update, $options ] ],
    [ 'updateOne'  => [ $filter, $update, $options ] ],
]

提示

要学习；了解有关删除、插入、替换和更新操作的更多信息，请参阅增删改查操作。

调用 bulkWrite() 方法时，库会按照数组中指定的顺序自动运行写入操作。要学习；了解如何指示 bulkWrite() 以任意顺序运行写入操作，请参阅修改批量写入行为。

例子

此示例对restaurants集合运行以下写入操作：

用于插入name值为'Mongo's Deli'的文档的插入操作
用于更新name值为'Mongo's Deli'的文档的cuisine字段的更新操作
删除操作，用于删除borough值为'Manhattan'的所有文档

$result = $collection->bulkWrite(
    [
        [
            'insertOne' => [
                ['name' => 'Mongo\'s Deli'], 
                ['cuisine' => 'Sandwiches'], 
                ['borough' => 'Manhattan'], 
                ['restaurant_id' => '1234'], 
            ],
        ],
        [
            'updateOne' => [
                ['name' => 'Mongo\'s Deli'], 
                ['$set' => ['cuisine' => 'Sandwiches and Salads']],
            ],
        ],
        [
            'deleteMany' => [
                ['borough' => 'Manhattan'],
            ],
        ],
    ],
);

修改批量写入行为

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

选项	说明
`bypassDocumentValidation`	指定操作是否绕过文档验证。这样，您就可以修改不符合模式验证要求的文档（如果存在）。模式验证有关模式验证的更多信息，请参阅MongoDB Server手册中的模式验证。默认为 `false`。
`codec`	设置用于对文档进行编码或解码的编解码器。批量写入使用编解码器进行 `insertOne()` 和 `replaceOne()` 操作。有关更多信息，请参阅使用类型编解码器对数据进行编码。
`writeConcern`	设置操作的写关注（write concern）。有关更多信息，请参阅MongoDB Server手册中的写关注。
`let`	指定包含值列表的文档，以提高操作的可读性。值必须是常量或不引用文档字段的闭合表达式。有关更多信息，请参阅MongoDB Server手册中的 let声明。
`ordered`	如果设置为 `true`：当单次写入失败时，操作将停止，不执行剩余写入，并抛出异常。如果设置为 `false`：当单次写入失败时，操作将继续尝试剩余写入操作（如有），然后抛出异常。默认为 `true`。
`comment`	为操作附加注释。有关更多信息，请参阅MongoDB Server手册中的插入命令字段指南。
`session`	指定与操作关联的客户端会话。

以下示例调用bulkWrite()方法执行插入和删除操作，并将ordered选项设置为false ：

$result = $collection->bulkWrite(
    [
        [
            'insertOne' => [
                ['name' => 'Mongo\'s Pizza'], 
                ['cuisine' => 'Italian'], 
                ['borough' => 'Queens'], 
                ['restaurant_id' => '5678'], 
            ],
        ],
        [
            'deleteOne' => [
                ['restaurant_id' => '5678'],
            ],
        ],
    ],
    ['ordered' => false],
);

如果库先运行插入操作，则会删除一个文档。如果它先运行删除操作，则不会删除任何文档。

注意

无序批量操作不保证执行顺序。为了优化运行时间，顺序可以与您列出的方式不同。

返回值

MongoDB\Collection::bulkWrite()方法返回一个MongoDB\BulkWriteResult对象。该类包含以下成员函数：

function	说明
`getDeletedCount()`	返回已删除的文档数量（如有）。
`getInsertedCount()`	返回插入的文档数（如果有）。
`getInsertedIds()`	返回插入的文档的 `_id`字段值的映射（如果有）。
`getMatchedCount()`	返回更新和替换操作期间匹配的文档数（如果适用）。
`getModifiedCount()`	返回已修改的文档数（如有）。
`getUpsertedCount()`	返回已更新或插入的文档数（如有）。
`getUpsertedIds()`	返回已更新或插入的文档的 `_id`字段值的映射（如果有）。
`isAcknowledged()`	返回一个布尔值，表示批量操作是否已确认。

批量写入操作

Overview

样本数据

批量操作

提示

例子

修改批量写入行为

注意

返回值

更多信息

API 文档