/ /

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 o 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 coleções sample_restaurants.restaurants e sample_mflix.movies dos conjuntos de dados de amostra do Atlas. Para **aprender** como criar um cluster gratuito do MongoDB Atlas e carregar os conjuntos de dados de amostra, consulte Introdução ao Atlas.

Gravação em massa do cliente

Ao usar a biblioteca PHP v2.1 e conectar-se a uma implantação executando o MongoDB Server 8.0 ou posterior, você pode usar o método MongoDB\Client::bulkWrite() para gravar 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`	Especifica se a operação ignora a validação do documento . Isso permite modificar documentos que não atendem aos requisitos de validação de esquema , se houver. Para obter mais informações sobre validação de esquema, consulte Validação de esquema no manual do MongoDB Server . O padrão `false` é.
`comment`	Anexa um comentário à operação. Para obter mais informações, consulte o guia de campos de comando de inserção no manual do MongoDB Server .
`let`	Especifica um documento com uma lista de valores para melhorar a legibilidade da operação. Os valores devem ser expressões constantes ou fechadas que não façam referência aos campos do documento . Para obter mais informações, consulte a declaração let no manual do MongoDB Server .
`ordered`	Se definido `true` como: quando uma única gravação falha, a operação para sem executar as gravações restantes e lança uma exceção. Se definido `false` como: quando uma única gravação falha, a operação continua tentando as operações de gravação restantes, se houver, e lança uma exceção. O padrão `true` é.
`verboseResults`	Especifica se deseja retornar resultados detalhados. O padrão `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()`	Retorna o número total de documentos inseridos por todas as operações de inserção no comando de gravação em massa.
`getMatchedCount()`	Retorna o número total de documentos correspondidos por todas as operações de atualização e substituição no comando de gravação em massa.
`getModifiedCount()`	Retorna o número total de documentos modificados por todas as operações de atualização e substituição no comando de gravação em massa.
`getUpsertedCount()`	Retorna o número total de documentos atualizados por todas as operações de atualização e substituição no comando de gravação em massa.
`getDeletedCount()`	Retorne o número total de documentos excluídos por todas as operações de exclusão no comando de gravação em massa.
`getInsertResults()`	Retorna um mapa de resultados de cada operação de inserção bem-sucedida. Cada operação é representada por uma chave de número inteiro, que contém um documento com informações correspondentes à operação, como o valor `_id` inserido.
`getUpdateResults()`	Retorna um mapa de resultados de cada operação de atualização bem-sucedida. Cada operação é representada por uma chave de número inteiro, que contém um documento com informações correspondentes à operação.
`getDeleteResults()`	Retorna um mapa de resultados de cada operação de exclusão bem-sucedida. Cada operação é representada por uma chave de número inteiro, que contém um documento com informações correspondentes à operação.
`isAcknowledged()`	Retorna um booleano indicando se o servidor reconheceu a operação em massa.

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 Operações CRUD.

Quando você chama o método bulkWrite(), a biblioteca executa automaticamente as operações de gravação na ordem especificada na array. Para **aprender** como instruir bulkWrite() a executar as operações de gravação em uma ordem arbitrária, consulte 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`	Especifica se a operação ignora a validação do documento . Isso permite modificar documentos que não atendem aos requisitos de validação de esquema , se houver. Para obter mais informações sobre validação de esquema, consulte Validação de esquema no manual do MongoDB Server . O padrão `false` é.
`codec`	Define o codec a ser usado para codificar ou decodificar documentos. As gravações em massa usam o codec para `insertOne()` `replaceOne()` operações e. Para obter mais informações, consulte Codificar dados com codecs de tipo.
`writeConcern`	Define a preocupação de gravação para a operação. Para obter mais informações, consulte Write Concern no manual do MongoDB Server .
`let`	Especifica um documento com uma lista de valores para melhorar a legibilidade da operação. Os valores devem ser expressões constantes ou fechadas que não façam referência aos campos do documento . Para obter mais informações, consulte a declaração let no manual do MongoDB Server .
`ordered`	Se definido `true` como: quando uma única gravação falha, a operação para sem executar as gravações restantes e lança uma exceção. Se definido `false` como: quando uma única gravação falha, a operação continua tentando as operações de gravação restantes, se houver, e lança uma exceção. O padrão `true` é.
`comment`	Anexa um comentário à operação. Para obter mais informações, consulte o guia de campos de comando de inserção no manual do MongoDB Server .
`session`	Especifica a sessão do cliente a ser associada à operação.

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()`	Retorna o número total de documentos inseridos por todas as operações de inserção no comando de gravação em massa.
`getInsertedIds()`	Retorna um mapa de `_id` valores de campo para documentos inseridos por todas as operações de inserção no comando de gravação em massa.
`getMatchedCount()`	Retorna o número total de documentos correspondidos por todas as operações de atualização e substituição no comando de gravação em massa.
`getModifiedCount()`	Retorna o número total de documentos modificados por todas as operações de atualização e substituição no comando de gravação em massa.
`getUpsertedCount()`	Retorna o número total de documentos atualizados por todas as operações de atualização e substituição no comando de gravação em massa.
`getUpsertedIds()`	Retorna um mapa de `_id` valores de campo para documentos atualizados por todas as operações de atualização e substituição no comando de gravação em massa.
`getDeletedCount()`	Retorne o número total de documentos excluídos por todas as operações de exclusão no comando de gravação em massa.
`isAcknowledged()`	Retorna um booleano indicando se o servidor reconheceu a operação em massa.

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

Exclua documentos

Transações