/ /

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 em uma coleção, 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 de dados. Em vez disso, você pode usar uma operação em massa para reduzir o número de chamadas para o banco de dados de dados.

Dados de amostra

Os exemplos neste guia usam a collection restaurants no banco de dados sample_restaurants dos conjuntos de banco de dados de amostra do Atlas. Para acessar essa coleção a partir do seu aplicação PHP , instancie um MongoDB\Client que se conecte a um Atlas cluster e atribua o seguinte valor à sua variável $collection :

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

Para aprender como criar um cluster gratuito do MongoDB Atlas e carregar os conjuntos de dados de amostra, consulte Introdução ao Atlas.

Operações em massa

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 em que são especificadas na array. Para saber como instruir bulkWrite() a executar as operações de gravação em uma ordem arbitrária, consulte Modificar comportamento 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'

$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'],
            ],
        ],
    ],
);

Modificar comportamento de escrita 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 = $collection->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

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 as seguintes funções de membro:

Função	Descrição
`getDeletedCount()`	Retorna o número de documentos excluídos, se houver.
`getInsertedCount()`	Retorna o número de documentos inseridos, se houver.
`getInsertedIds()`	Retorna um mapa de `_id` valores de campo para documentos inseridos, se houver.
`getMatchedCount()`	Retorna o número de documentos correspondidos durante as operações de atualização e substituição, se aplicável.
`getModifiedCount()`	Retorna o número de documentos modificados, se houver.
`getUpsertedCount()`	Retorna o número de documentos atualizados, se houver.
`getUpsertedIds()`	Retorna um mapa de `_id` valores de campo para documentos atualizados, se houver.
`isAcknowledged()`	Retorna um booleano indicando se a operação em massa foi reconhecida.

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:

Voltar

Exclua documentos

Transações