批量写入操作

在本页

概述

示例数据
批量操作
示例
修改批量写入行为
返回值
更多信息
API文档

概述

本指南将向您介绍如何通过使用批量写入操作在单个数据库调用中执行多个写入操作。

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

示例数据

本指南中的示例使用来自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'
更新操作，更新一个文档的 cuisine 字段，其中 name 值为 'Mongo's Deli'
删除操作，删除所有 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 服务器手册中的模式验证。默认为 `false`。
`codec`	设置用于编码或解码文档的编解码器。批量写入使用 `insertOne()` 和 `replaceOne()` 操作的编解码器。有关更多信息，请参阅编解码器指南。
`writeConcern`	设置操作的写入关注点。有关更多信息，请参阅 MongoDB 服务器手册中的写入关注点。
`let`	指定一个包含值列表的文档，以提高操作的可读性。值必须是常数或闭包表达式，不能引用文档字段。有关更多信息，请参阅MongoDB服务器手册中的 let语句。
`有序`	如果设置为`true`：当单个写操作失败时，操作将停止而不会执行剩余的写操作，并抛出异常。如果设置为`false`：当单个写操作失败时，操作将继续尝试执行剩余的写操作（如果有），然后抛出异常。默认为`true`。
`注释`	将注释附加到操作上。有关更多信息，请参阅MongoDB服务器手册中的插入命令字段指南。
`会话`	指定要关联操作的客户端会话。

以下示例调用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对象。该类包含以下成员函数

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

附加信息

要了解如何执行单个写操作，请参阅以下指南

API 文档

要了解更多关于本指南中讨论的任何方法或类型的信息，请参阅以下API文档

替换

事务