Operações de gravação em massa

Nesta página

Visão geral
Dados de amostra
Operações em massa
Exemplo
Modificar comportamento de escrita em massa
Valor de retorno
Informações adicionais
Documentação da API

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 utilizam a coleção do restaurants no banco de dados de dados do sample_restaurants a partir dos conjuntos 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 saber como criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de amostra, consulte o guia Iniciar com 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 obter mais informações sobre as operações de exclusão, inserção, substituição e atualização, consulte osguias de operação de gravação .

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 a seção 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`	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. Defaults to `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. Defaults to `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 = $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()`	Returns the number of documents deleted, if any.
`getInsertedCount()`	Returns the number of documents inserted, if any.
`getInsertedIds()`	Returns a map of `_id` field values for inserted documents, if any.
`getMatchedCount()`	Returns the number of documents matched during update and replace operations, if applicable.
`getModifiedCount()`	Returns the number of documents modified, if any.
`getUpsertedCount()`	Returns the number of documents upserted, if any.
`getUpsertedIds()`	Returns a map of `_id` field values for upserted documents, if any.
`isAcknowledged()`	Returns a boolean indicating whether the bulk operation was acknowledged.

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

Substituir

Transações