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.
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 servidor MongoDB.
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" })
Chame 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 write concern 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 |
|---|---|
ordered | Se True, o driver executa as operações de gravação na ordem fornecida. Se ocorrer um erro, as operações restantes não serão tentadas.Se False, o driver executará as operações em uma ordem arbitrária e tentará executar todas as operações.Padrão é True. |
bypass_document_validation | Especifica se a operação ignora a validação em nível de documento. Para obter mais informações, consulte Validação de esquema no manual do MongoDB Server . Padrão é False. |
session | Uma instância de ClientSession. Para obter mais informações, consulte a documentação da API. |
comment | Um comentário a ser anexado à operação. Para obter mais informações, consulte o guia de campos de comando de exclusão no manual do MongoDB Server . |
let | Um mapa de nomes e valores de parâmetros. 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 . |
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 |
|---|---|
acknowledged | Indica se o servidor reconheceu a operação de gravação. |
bulk_api_result | O resultado bruto da API em massa retornado pelo servidor. |
deleted_count | O número de documentos excluídos, se houver. |
inserted_count | O número de documentos inseridos, se houver. |
matched_count | O número de documentos correspondentes para uma atualização, se aplicável. |
modified_count | O número de documentos modificados, se houver. |
upserted_count | O número de documentos atualizados, se houver. |
upserted_ids | Um mapa do índice da operação para o _id dos documentos atualizados, se aplicável. |
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: