Operações de gravação em massa

Visão geral

Neste guia, você aprenderá a executar várias operações de gravação em uma única chamada de banco de dados de dados usando operações de gravação em massa.

Considere um cenário no qual você deseja inserir um documento, atualizar vários outros documentos e excluir um documento. Se você usar métodos individuais, cada operação exigirá sua própria chamada de banco de dados .

Ao usar uma operação de gravação em massa, você pode executar várias operações de gravação em menos chamadas de banco de dados . Você pode realizar operações de gravação em massa nos seguintes níveis:

Cliente: Se seu aplicação se conectar ao MongoDB Server versão 8.0 ou posterior, você poderá usar o método MongoDB\Client::bulkWrite() para executar operações de gravação em massa em várias collections e bancos de dados no mesmo cluster. Este método executa todas as operações de gravação em uma chamada de banco de dados . Para saber mais sobre esse recurso, consulte o Mongo.bulkWrite() referência no manual do MongoDB Server .
Collection: você pode usar o método MongoDB\Collection::bulkWrite() para executar operações de escrita em massa em uma única collection. Este método faz uma chamada de banco de dados para cada tipo de operação de gravação. Por exemplo, o método pode executar várias operações de atualização em uma chamada, mas faz duas chamadas separadas para o banco de dados para uma operação de inserção e uma operação de substituição.

Dados de amostra

Os exemplos neste guia usam as sample_restaurants.restaurants sample_mflix.movies collections e dos conjuntos de dados de amostra do Atlas . Para saber como criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de amostra, consulte o guia Iniciar com Atlas .

Gravação em massa do cliente

Ao utilizar a biblioteca PHP v2.1 e conectar a uma implantação executando o MongoDB Server 8.0 ou posterior, você pode utilizar o método MongoDB\Client::bulkWrite() para escrever em vários bancos de dados e coleções no mesmo cluster. Este método executa todas as operações de gravação em uma única chamada.

Primeiro, utilize o MongoDB\ClientBulkWrite construtor para criar uma instância BulkWriteCommand que especifica as operações de gravação para executar. O código a seguir demonstra como criar uma instância ClientBulkWrite a partir de uma instância MongoDB\Collection usando o método createWithCollection():

$restaurantCollection = $client->sample_restaurants->restaurants;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);

Em seguida, chame um ou mais dos seguintes métodos de gravação na instância ClientBulkWrite para construir a operação de gravação em massa:

deleteOne()
deleteMany()
insertOne()
replaceOne()
updateOne()
updateMany()

Para selecionar um namespace diferente para operações de gravação subsequentes, chame o método withCollection() na instância ClientBulkWrite, conforme mostrado no código a seguir:

$movieCollection = $client->sample_mflix->movies;
$bulkWrite = $bulkWrite->withCollection($movieCollection);

As seções a seguir mostram como criar e usar a classe ClientBulkWrite para especificar operações de gravação em uma gravação em massa. A seção Executar a operação em massa demonstra como passar o objeto ClientBulkWrite para o método bulkWrite() para executar a operação em massa.

Inserir operações

Para especificar uma operação de inserção, chame o método insertOne() em sua instância ClientBulkWrite.

O exemplo a seguir especifica a inserção de documentos nas collections sample_restaurants.restaurants e sample_mflix.movies:

$restaurantCollection = $client->sample_restaurants->restaurants;
$movieCollection = $client->sample_mflix->movies;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
$bulkWrite->insertOne(['name' => 'Mongo Deli', 'cuisine' => 'Sandwiches']);
$bulkWrite = $bulkWrite->withCollection($movieCollection);
$bulkWrite->insertOne(['title' => 'The Green Ray', 'year' => 1986]);

Atualizar operações

Para especificar uma operação de atualização no primeiro documento correspondente, chame o método updateOne() na sua instância ClientBulkWrite.

O exemplo a seguir especifica uma atualização $set para o primeiro documento na collection sample_restaurants.restaurants que tem um valor name de 'Dandelion Bakery':

$restaurantCollection = $client->sample_restaurants->restaurants;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
$bulkWrite->updateOne(
    ['name' => 'Dandelion Bakery'],
    ['$set' => ['grade' => 'B+']],
    ['upsert' => true],
);

Para atualizar vários documentos, chame o método updateMany(). A operação especificada atualiza todos os documentos que correspondem ao filtro de consulta.

O exemplo a seguir especifica uma atualização $set para todos os documentos correspondentes na collection sample_restaurants.restaurants que têm um valor name de 'Starbucks':

$restaurantCollection = $client->sample_restaurants->restaurants;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
$bulkWrite->updateMany(
    ['name' => 'Starbucks'],
    ['$set' => ['cuisine' => 'Coffee (Chain)']],
);

Operações de substituição

Para especificar uma operação de substituição no primeiro documento correspondente, chame o método replaceOne() na sua instância ClientBulkWrite.

O exemplo a seguir especifica uma operação de substituição no primeiro documento da collection sample_restaurants.restaurants que tem um valor name de 'Dandelion Bakery':

$restaurantCollection = $client->sample_restaurants->restaurants;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
$bulkWrite->replaceOne(
    ['name' => 'Dandelion Bakery'],
    ['name' => 'Flower Patisserie', 'cuisine' => 'Bakery & Cafe'],
);

Excluir operações

Para especificar uma operação de exclusão no primeiro documento correspondente, chame o método deleteOne() na sua instância ClientBulkWrite.

O exemplo a seguir especifica a exclusão do primeiro documento na collection sample_restaurants.restaurants que tem um valor borough de 'Queens':

$restaurantCollection = $client->sample_restaurants->restaurants;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
$bulkWrite->deleteOne(
    ['borough' => 'Queens'],
);

Para excluir vários documentos, chame o método deleteMany(). A operação especificada exclui todos os documentos que correspondem ao filtro de query.

O exemplo a seguir especifica a exclusão de todos os documentos na collection sample_restaurants.restaurants que têm um valor name que contém dois 'p' caracteres consecutivos:

$restaurantCollection = $client->sample_restaurants->restaurants;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
$bulkWrite->deleteMany(
    ['name' => ['$regex' => 'p{2,}']],
);

Executar a operação em massa

Depois de construir a instância ClientBulkWrite para especificar suas operações de gravação, passe para o método MongoDB\Client::bulkWrite() . Por padrão, estes métodos executam as operações na ordem definida ao construir o ClientBulkWrite.

O seguinte código demonstra como utilizar o método bulkWrite() para executar uma operação de escrita em massa em múltiplos namespaces:

$restaurantCollection = $client->sample_restaurants->restaurants;
$movieCollection = $client->sample_mflix->movies;
// Creates the bulk write command and sets the target namespace.
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
// Specifies insertion of one document.
$bulkWrite->insertOne(['name' => 'Mongo Deli', 'cuisine' => 'Sandwiches']);
// Specifies a `$set` update to one document with the upsert option
// enabled.
$bulkWrite->updateOne(
    ['name' => 'Dandelion Bakery'],
    ['$set' => ['grade' => 'B+']],
    ['upsert' => true],
);
// Changes the target namespace.
$bulkWrite = $bulkWrite->withCollection($movieCollection);
// Specifies insertion of one document.
$bulkWrite->insertOne(['title' => 'The Green Ray', 'year' => 1986]);
// Specifies deletion of documents in which `title` has two consective
// 'd' characters.
$bulkWrite->deleteMany(
    ['title' => ['$regex' => 'd{2,}']],
);
// Specifies replacement of one document.
$bulkWrite->replaceOne(
    ['runtime' => ['$gte' => 200]],
    ['title' => 'Seven Samurai', 'runtime' => 203],
);
// Performs the bulk write operation.
$result = $client->bulkWrite($bulkWrite);
// Prints a summary of results.
echo 'Inserted documents: ', $result->getInsertedCount(), PHP_EOL;
echo 'Modified documents: ', $result->getModifiedCount(), PHP_EOL;
echo 'Deleted documents: ', $result->getDeletedCount(), PHP_EOL;

Inserted documents: 2
Modified documents: 2
Deleted documents: 200

Personalizar escrita em massa

Você pode modificar o comportamento da operação de gravação em massa do cliente passando uma array para o construtor ClientBulkWrite que especifica valores de opção como um parâmetro. A tabela a seguir descreve as opções que você pode definir na array:

Opção	Descrição
`bypassDocumentValidation`	Specifies whether the operation bypasses document validation. This lets you modify 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. The default is `false`.
`comment`	Attaches a comment to the operation. For more information, see the insert command fields guide in the MongoDB Server manual.
`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.
`ordered`	If set to `true`: When a single write fails, the operation stops without performing the remaining writes and throws an exception. If set to `false`: When a single write fails, the operation continues to attempt the remaining write operations, if any, then throws an exception. The default is `true`.
`verboseResults`	Specifies whether to return verbose results. The default is `false`.

O exemplo seguinte cria uma instância ClientBulkWrite e define a opção ordered como false:

$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection(
    $restaurantCollection,
    ['ordered' => false]
);

Observação

Comportamento não ordenado

Operações em massa não ordenadas não garantem ordem de execução. A ordem pode ser diferente da forma como você os lista para otimizar o tempo de execução. Suponha que você especifique as seguintes operações de gravação em uma gravação em massa não ordenada:

$bulkWrite->insertOne(['_id' => 4045, 'title' => 'The Green Ray']);
$bulkWrite->deleteOne(['_id' => 4045]);

Como a biblioteca pode executar qualquer operação primeiro, o resultado pode mostrar um documento excluído ou nenhum documento excluído.

Você também pode passar opções ao chamar o método bulkWrite() para especificar a sessão do cliente ou a preocupação de gravação a ser usada na operação.

Valor de retorno

O método MongoDB\Client::bulkWrite() retorna um objeto MongoDB\BulkWriteCommandResult. Esta classe contém os seguintes métodos:

Método	Descrição
`getInsertedCount()`	Returns the total number of documents inserted by all insert operations in the bulk write command.
`getMatchedCount()`	Returns the total number of documents matched by all update and replace operations in the bulk write command.
`getModifiedCount()`	Returns the total number of documents modified by all update and replace operations in the bulk write command.
`getUpsertedCount()`	Returns the total number of documents upserted by all update and replace operations in the bulk write command.
`getDeletedCount()`	Return the total number of documents deleted by all delete operations in the bulk write command.
`getInsertResults()`	Returns a map of results of each successful insert operation. Each operation is represented by an integer key, which contains a document with information corresponding to the operation such as the inserted `_id` value.
`getUpdateResults()`	Returns a map of results of each successful update operation. Each operation is represented by an integer key, which contains a document with information corresponding to the operation.
`getDeleteResults()`	Returns a map of results of each successful delete operation. Each operation is represented by an integer key, which contains a document with information corresponding to the operation.
`isAcknowledged()`	Returns a boolean indicating whether the server acknowledged the bulk operation.

Gravação em massa de collections

Para executar uma operação de gravação em massa, passe uma array de operações de gravação para o método MongoDB\Collection::bulkWrite(). Use a seguinte sintaxe para especificar as operações de gravação:

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

Dica

Para saber mais sobre excluir, inserir, substituir e atualizar operações, consulte os guias na seção Gravar dados no MongoDB.

Quando você chama o método bulkWrite(), a biblioteca executa automaticamente as operações de gravação na ordem especificada na array. Para saber como instruir bulkWrite() a executar as operações de gravação em uma ordem arbitrária, consulte a seção Personalizar operação de gravação em massa.

Exemplo

Este exemplo executa as seguintes operações de gravação na coleção restaurants :

Insira a operação para inserir um documento no qual o valor de name é 'Mongo's Deli'
Operação de atualização para atualizar o campo cuisine de um documento no qual o valor name é 'Mongo's Deli'
Operação Excluir para excluir todos os documentos em que o valor borough é 'Manhattan'

$restaurantCollection = $client->sample_restaurants->restaurants;
$result = $restaurantCollection->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'],
            ],
        ],
    ]
);

Observação

Quando a biblioteca executa uma operação em massa, ela usa a preocupação de gravação da coleção de destino. O driver relata todos os erros de preocupação de gravação depois de tentar todas as operações, independentemente da ordem de execução.

Personalizar operação de gravação em massa

Você pode modificar o comportamento do método MongoDB\Collection::bulkWrite() passando uma array que especifique valores de opção como um parâmetro. A tabela a seguir descreve as opções que você pode definir na array:

Opção	Descrição
`bypassDocumentValidation`	Specifies whether the operation bypasses document validation. This lets you modify 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. The default is `false`.
`codec`	Sets the codec to use for encoding or decoding documents. Bulk writes use the codec for `insertOne()` and `replaceOne()` operations. For more information, see the Codecs guide.
`writeConcern`	Sets the write concern for the operation. For more information, see Write Concern in the MongoDB Server manual.
`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.
`ordered`	If set to `true`: When a single write fails, the operation stops without performing the remaining writes and throws an exception. If set to `false`: When a single write fails, the operation continues to attempt the remaining write operations, if any, then throws an exception. The default is `true`.
`comment`	Attaches a comment to the operation. For more information, see the insert command fields guide in the MongoDB Server manual.
`session`	Specifies the client session to associate with the operation.

O exemplo seguinte chama o método bulkWrite() para executar uma operação de inserção e exclusão e define a opção ordered como false:

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

Se a biblioteca executar a operação de inserção primeiro, um documento será excluído. Se executar a operação de exclusão primeiro, nenhum documento será excluído.

Observação

Comportamento não ordenado

Operações em massa não ordenadas não garantem ordem de execução. A ordem pode ser diferente da forma como você os lista para otimizar o tempo de execução.

Valor de retorno

O método MongoDB\Collection::bulkWrite() retorna um objeto MongoDB\BulkWriteResult. Esta classe contém os seguintes métodos:

Método	Descrição
`getInsertedCount()`	Returns the total number of documents inserted by all insert operations in the bulk write command.
`getInsertedIds()`	Returns a map of `_id` field values for documents inserted by all insert operations in the bulk write command.
`getMatchedCount()`	Returns the total number of documents matched by all update and replace operations in the bulk write command.
`getModifiedCount()`	Returns the total number of documents modified by all update and replace operations in the bulk write command.
`getUpsertedCount()`	Returns the total number of documents upserted by all update and replace operations in the bulk write command.
`getUpsertedIds()`	Returns a map of `_id` field values for documents upserted by all update and replace operations in the bulk write command.
`getDeletedCount()`	Return the total number of documents deleted by all delete operations in the bulk write command.
`isAcknowledged()`	Returns a boolean indicating whether the server acknowledged the bulk operation.

Informações adicionais

Para saber como realizar operações de escrita individuais, consulte os seguintes guias:

Documentação da API

Para saber mais sobre qualquer um dos métodos ou tipos discutidos neste guia, consulte a seguinte documentação da API:

Gravação em massa do cliente
Gravação em massa de collections
- MongoDB\Collection::bulkWrite()
- MongoDB\BulkWriteResult

Voltar

Substituir

Transações