Operações de gravação em massa
Nesta página
Visão geral
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. Este guia mostra como usar operações de gravação em massa para executar várias operações de gravação em uma única chamada de banco de dados.
Dados de amostra
Os exemplos neste guia usam a collection sample_restaurants.restaurants dos conjuntos de dados de amostra do Atlas. Para saber como criar um cluster gratuito do MongoDB Atlas e carregar os conjuntos de dados de amostra, consulte o tutorial Introdução ao PyMongo .
Definir as operações de gravação
Para cada operação de gravação que você deseja executar, crie uma instância de uma das seguintes classes de operação:
InsertOneUpdateOneUpdateManyReplaceOneDeleteOneDeleteMany
Em seguida, passe uma lista dessas instâncias para o método bulk_write() .
As seções seguintes mostram como criar e utilizar instâncias das classes anteriores.
Inserir operações
Para executar uma operação de inserção, crie uma instância de InsertOne e especifique o documento que você deseja inserir.
O exemplo a seguir cria uma instância de InsertOne:
operation = pymongo.InsertOne( { "name": "Mongo's Deli", "cuisine": "Sandwiches", "borough": "Manhattan", "restaurant_id": "1234" } )
Para inserir vários documentos, crie uma instância de InsertOne para cada documento.
Observação
Os valores duplicados de _id violam restrições de índice único , o que faz com que o driver retorne um DuplicateKeyError. Para evitar esse erro, certifique-se de que cada documento inserido tenha um valor _id exclusivo.
Atualizar operações
Para atualizar um documento, crie uma instância de UpdateOne e passe os seguintes argumentos:
Um filtro de query que especifica os critérios usados para corresponder aos documentos em sua coleção
A operação de atualização que você deseja executar. Para obter mais informações sobre operações de atualização, consulte o guia Operadores de atualização de campo no manual do MongoDB Server .
UpdateOne atualiza o primeiro documento que corresponde ao seu filtro de query.
O exemplo a seguir cria uma instância de UpdateOne:
operation = pymongo.UpdateOne( { "name": "Mongo's Deli" }, { "$set": { "cuisine": "Sandwiches and Salads" }}, )
Para atualizar vários documentos, crie uma instância de UpdateMany e passe os mesmos argumentos. UpdateMany atualiza todos os documentos que correspondem ao seu filtro de query.
O exemplo a seguir cria uma instância de UpdateMany:
operation = pymongo.UpdateMany( { "name": "Mongo's Deli" }, { "$set": { "cuisine": "Sandwiches and Salads" }}, )
Operações de substituição
Uma operação de substituição remove todos os campos e valores de um documento especificado e os substitui por novos. Para executar uma operação de substituição, crie uma instância de ReplaceOne e passe um filtro de query e os campos e valores que você deseja armazenar no documento correspondente.
O exemplo a seguir cria uma instância de ReplaceOne:
operation = pymongo.ReplaceOne( { "restaurant_id": "1234" }, { "name": "Mongo's Pizza", "cuisine": "Pizza", "borough": "Brooklyn", "restaurant_id": "5678" } )
Para substituir vários documentos, você deve criar uma instância de ReplaceOne para cada documento.
Excluir operações
Para excluir um documento, crie uma instância do DeleteOne e passe um filtro de query especificando o documento que você deseja excluir. DeleteOne remove somente o primeiro documento que corresponde ao seu filtro de query.
O exemplo a seguir cria uma instância de DeleteOne:
operation = pymongo.DeleteOne({ "restaurant_id": "5678" })
Para excluir vários documentos, crie uma instância do DeleteMany e passe um filtro de query especificando o documento que você deseja excluir. DeleteMany remove todos os documentos que correspondem ao seu filtro de query.
O exemplo a seguir cria uma instância de DeleteMany:
operation = pymongo.DeleteMany({ "name": "Mongo's Deli" })
Ligue para o bulk_write() método
Depois de definir uma instância de classe para cada operação que deseja executar, passe uma lista dessas instâncias para o método bulk_write() . Por padrão, o método executa as operações na ordem em que foram definidas na lista.
O exemplo a seguir executa diversas operações de gravação usando o método bulk_write() :
operations = [ pymongo.InsertOne( { "name": "Mongo's Deli", "cuisine": "Sandwiches", "borough": "Manhattan", "restaurant_id": "1234" } ), pymongo.InsertOne( { "name": "Mongo's Deli", "cuisine": "Sandwiches", "borough": "Brooklyn", "restaurant_id": "5678" } ), pymongo.UpdateMany( { "name": "Mongo's Deli" }, { "$set": { "cuisine": "Sandwiches and Salads" }}, ), pymongo.DeleteOne( { "restaurant_id": "1234" } ) ] results = restaurants.bulk_write(operations) print(results)
BulkWriteResult({'writeErrors': [], 'writeConcernErrors': [], 'nInserted': 2, 'nUpserted': 0, 'nMatched': 2, 'nModified': 2, 'nRemoved': 1, 'upserted': []}, acknowledged=True)
Se qualquer uma das operações de gravação falhar, o PyMongo gerará um BulkWriteError e não executará mais nenhuma operação. BulkWriteError fornece um atributo details que inclui a operação que falhou e detalhes sobre a exceção.
Observação
Quando o PyMongo executa uma operação em massa, ele usa o write_concern da collection na qual a operação está sendo executada. 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ções de gravação em massa
Opcionalmente, o método bulk_write() aceita parâmetros adicionais, que representam opções que você pode usar para configurar a operação de gravação em massa. Se você não especificar nenhuma opção adicional, o driver não personalizará a operação de gravação em massa.
Propriedade | Descrição |
|---|---|
| If True, the driver performs the write operations in the order
provided. If an error occurs, the remaining operations are not
attempted.If False, the driver performs the operations in an
arbitrary order and attempts to perform all operations.Defaults to True. |
| Specifies whether the operation bypasses document-level validation. For more
information, see Schema
Validation in the MongoDB
Server manual. Defaults to False. |
| An instance of ClientSession. For more information, see the API
documentation. |
| A comment to attach to the operation. For more information, see the delete command
fields guide in the
MongoDB Server manual. |
| A map of parameter names and values. 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. |
O exemplo seguinte chama o método bulk_write() do exemplo anterior, com a opção ordered definida como False:
results = restaurants.bulk_write(operations, ordered=False)
Se qualquer uma das operações de gravação em uma gravação em massa não ordenada falhar, o PyMongo relatará os erros somente depois de tentar todas as operações.
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 bulk_write() retorna um objeto BulkWriteResult . O objeto BulkWriteResult contém as seguintes propriedades:
Propriedade | Descrição |
|---|---|
| Indicates if the server acknowledged the write operation. |
| The raw bulk API result returned by the server. |
| The number of documents deleted, if any. |
| The number of documents inserted, if any. |
| The number of documents matched for an update, if applicable. |
| The number of documents modified, if any. |
| The number of documents upserted, if any. |
| A map of the operation's index to the _id of the upserted documents, if
applicable. |
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: