Operações de gravação em massa

Nesta página

Visão geral

Dados de amostra
Definir as operações de gravação
Inserir operações
Atualizar operações
Operações de substituição
Excluir operações
Executar a operação em massa
Personalizar operação de gravação em massa
Valor de retorno
Informações adicionais
Documentação da API

Visão geral

Este guia mostra como usar o driver Scala para executar uma operação de gravação em massa que faz várias alterações em seus dados em uma única chamada de banco de dados .

Considere uma situação que exige que você insira documentos, atualize documentos e exclua documentos para a mesma tarefa. Se você usar os métodos de gravação individuais para executar cada tipo de operação, cada gravação acessará o banco de dados de dados separadamente. Você pode usar uma operação de gravação em massa para otimizar o número de chamadas que seu aplicação faz para o servidor.

Dados de amostra

Os exemplos deste guia usam a restaurants coleção no sample_restaurants banco de dados dos conjuntos de dados de amostra do Atlas . Para acessar essa coleção a partir do seu aplicação Scala, crie um MongoClient que se conecte a um Atlas cluster e atribua os seguintes valores às suas variáveis database collection e:

val database: MongoDatabase = mongoClient.getDatabase("sample_restaurants")
val collection: MongoCollection[Document] = database.getCollection("restaurants")

Para saber como criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de amostra, consulte o guia Iniciar com Atlas .

Definir as operações de gravação

Para cada operação de gravação que você deseja executar, crie uma instância correspondente de uma das seguintes classes de operação que herdam da classe genérica WriteModel :

InsertOneModel
UpdateOneModel
UpdateManyModel
ReplaceOneModel
DeleteOneModel
DeleteManyModel

Em seguida, passe uma lista dessas instâncias para o método bulkWrite() .

As seções seguintes mostram como criar e utilizar instâncias das classes anteriores. A seção Executar a operação em massa demonstra como passar uma lista de modelos para o método bulkWrite() para executar a operação em massa.

Inserir operações

Para executar uma operação de inserção, crie uma instância do InsertOneModel e especifique o documento que você deseja inserir.

O exemplo a seguir cria uma instância de InsertOneModel:

val insertOneModel = InsertOneModel(
    Document("name" -> "Blue Moon Grill",
             "borough" -> "Brooklyn",
             "cuisine" -> "American")
)

Para inserir vários documentos, crie uma instância de InsertOneModel para cada documento.

Importante

Ao executar uma operação em massa, o InsertOneModel não pode inserir um documento com um _id que já existe na coleção. Nessa situação, o driver lança um MongoBulkWriteException.

Atualizar operações

Para atualizar um documento, crie uma instância de UpdateOneModel e passe os seguintes argumentos:

Filtro de query que especifica os critérios usados para corresponder aos documentos em sua coleção.
Atualize a operaçã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 .

O exemplo a seguir cria uma instância de UpdateOneModel:

val updateOneFilter = equal("name", "White Horse Tavern")
val updateOneDoc = set("borough", "Queens")
val updateOneModel = UpdateOneModel(updateOneFilter, updateOneDoc)

Se vários documentos corresponderem ao filtro de query especificado na instância UpdateOneModel, a operação atualizará o primeiro resultado. Você pode especificar uma classificação em uma instância do UpdateOptions para aplicar um pedido aos documentos correspondentes antes que o driver execute a operação de atualização, conforme mostrado no código a seguir:

val options = UpdateOptions.sort(ascending("name"))

Para atualizar vários documentos, crie uma instância de UpdateManyModel e passe os mesmos argumentos de UpdateOneModel. A classe UpdateManyModel especifica atualizações para todos os documentos que correspondem ao seu filtro de query.

O exemplo a seguir cria uma instância de UpdateManyModel:

val updateManyFilter = equal("name", "Wendy's")
val updateManyDoc = set("cuisine", "Fast food")
val updateManyModel = UpdateOneModel(updateManyFilter, updateManyDoc)

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 campos e valores especificados por você. Para executar uma operação de substituição, crie uma instância de ReplaceOneModel e passe os seguintes argumentos:

Filtro de query que especifica os critérios usados para corresponder aos documentos em sua coleção
documento de substituição que especifica os novos campos e valores a inserir

O exemplo a seguir cria uma instância de ReplaceOneModel:

val replaceFilter = equal("name", "Cooper Town Diner")
val replaceDoc = Document("name" -> "Smith Town Diner",
                          "borough" -> "Brooklyn",
                          "cuisine" -> "American")
val replaceOneModel = ReplaceOneModel(replaceFilter, replaceDoc)

Se vários documentos corresponderem ao filtro de query especificado na instância ReplaceOneModel, a operação substituirá o primeiro resultado. Você pode especificar uma classificação em uma instância do ReplaceOptions para aplicar um pedido aos documentos correspondentes antes que o driver execute a operação de substituição, conforme mostrado no código a seguir:

val options = ReplaceOptions.sort(ascending("name"))

Dica

Substituir vários documentos

Para substituir vários documentos, crie uma instância de ReplaceOneModel para cada documento.

Excluir operações

Para excluir um documento, crie uma instância de DeleteOneModel e passe um filtro de query especificando o documento que deseja excluir. Uma instância do DeleteOneModel fornece instruções para excluir somente o primeiro documento que corresponde ao seu filtro de query.

O exemplo a seguir cria uma instância de DeleteOneModel:

val deleteOneModel = DeleteOneModel(equal("name", "Morris Park Bake Shop"))

Para excluir vários documentos, crie uma instância de DeleteManyModel e passe um filtro de query especificando o documento que deseja excluir. Uma instância de DeleteManyModel fornece instruções para remover todos os documentos que correspondem ao seu filtro de query.

O exemplo a seguir cria uma instância de DeleteManyModel:

val deleteManyModel = DeleteManyModel(equal("cuisine", "Experimental"))

Executar a operação em massa

Depois de definir uma instância de modelo para cada operação que deseja executar, passe uma lista dessas instâncias para o método bulkWrite() . Por padrão, o método executa as operações na ordem especificada pela lista de modelos.

O exemplo a seguir executa diversas operações de gravação usando o método bulkWrite() :

val insertOneModel = InsertOneModel(
    Document("name" -> "Red's Pizza",
             "borough" -> "Brooklyn",
             "cuisine" -> "Pizzeria")
)
val updateOneModel = UpdateOneModel(equal("name", "Moonlit Tavern"), set("borough", "Queens"))
val deleteManyModel = DeleteManyModel(equal("name", "Crepe"))
val writes = Seq(insertOneModel, updateOneModel, deleteManyModel)
val observable = collection.bulkWrite(writes)
observable.subscribe(
  (result: BulkWriteResult) => println(s"Success: $result"),
  (error: Throwable) => println(s"Error: ${error.getMessage}"),
  () => println("Completed")
)

Success: AcknowledgedBulkWriteResult{insertedCount=1, matchedCount=1, removedCount=1,
modifiedCount=1, upserts=[], inserts=[BulkWriteInsert{index=0, id=BsonObjectId{value=...}}]}
Completed

Se qualquer uma das operações de gravação falhar, o driver Scala emitirá um BulkWriteError e não executará mais nenhuma operação. BulkWriteError fornece um item details que inclui a operação que falhou e detalhes sobre a exceção.

Observação

Quando o driver executa uma operação em massa, ele usa a preocupação de gravação da collection 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

O método bulkWrite() aceita opcionalmente um parâmetro BulkWriteOptions, que especifica as opções que você pode usar para configurar a operação de gravação em massa. Se você não especificar nenhuma opção, o driver executará a operação em massa com as configurações padrão.

A tabela a seguir descreve os métodos de configuração que você pode usar para configurar uma instância BulkWriteOptions :

Método	Descrição
`ordered()`	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`.
`bypassDocumentValidation()`	Specifies whether the update operation bypasses document validation. This lets you update 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`.
`comment()`	Sets a comment to attach to the operation.
`let()`	Provides a map of parameter names and values to set top-level variables for the operation. Values must be constant or closed expressions that don't reference document fields.

O código a seguir cria opções e define a opção ordered como false para especificar uma escrita em massa não ordenada. Em seguida, o exemplo utiliza o método bulkWrite() para executar uma operação em massa:

val options = BulkWriteOptions().ordered(false)
val observable = collection.bulkWrite(writes, options)

Se qualquer uma das operações de escrita em uma escrita em massa não ordenada falhar, o driver Scala relatará os erros somente após tentar todas as operações.

Observação

Operações em massa não ordenadas não garantem uma 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 bulkWrite() retorna um objeto SingleObservable que contém um BulkWriteResult. Você pode acessar informações da instância BulkWriteResult assinando o observable e usando os seguintes métodos:

Método	Descrição
`wasAcknowledged()`	Indicates if the server acknowledged the write operation.
`getDeletedCount()`	The number of documents deleted, if any.
`getInsertedCount()`	The number of documents inserted, if any.
`getInserts()`	The list of inserted documents, if any.
`getMatchedCount()`	The number of documents matched for an update, if applicable.
`getModifiedCount()`	The number of documents modified, if any.
`getUpserts()`	The list of upserted documents, if any.

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

Excluir

Transações