Operações de gravação em massa
Nesta página
Visão geral
Este guia mostra como usar o driver Kotlin Sync 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 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 neste guia usam a collection sample_restaurants.restaurants dos conjuntos de dados de amostra do Atlas. Para saber como criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de amostra, consulte o guia Iniciar com Atlas .
Os documentos nesta coleção são modelados pela seguinte classe de dados Kotlin :
data class Restaurant( val name: String, val borough: String, val cuisine: String )
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 :
InsertOneModelUpdateOneModelUpdateManyModelReplaceOneModelDeleteOneModelDeleteManyModel
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 blueMoon = InsertOneModel(Restaurant("Blue Moon Grill", "Brooklyn", "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:
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 .
Uma instância UpdateOneModel especifica uma atualização para o primeiro documento que corresponde ao seu filtro de query.
O exemplo a seguir cria uma instância de UpdateOneModel:
val updateOneFilter = Filters.eq(Restaurant::name.name, "White Horse Tavern") val updateOneDoc = Updates.set(Restaurant::borough.name, "Queens") val tavernUpdate = UpdateOneModel<Restaurant>(updateOneFilter, updateOneDoc)
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 = Filters.eq(Restaurant::name.name, "Wendy's") val updateManyDoc = Updates.set(Restaurant::cuisine.name, "Fast food") val wendysUpdate = UpdateManyModel<Restaurant>(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 um filtro de query e os campos e valores pelos quais você deseja substituir o documento correspondente.
O exemplo a seguir cria uma instância de ReplaceOneModel:
val replaceFilter = Filters.eq(Restaurant::name.name, "Cooper Town Diner") val replaceDoc = Restaurant("Smith Town Diner", "Brooklyn", "American") val replacement = ReplaceOneModel(replaceFilter, replaceDoc)
Para substituir vários documentos, você deve criar 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 deleteOne = DeleteOneModel<Restaurant>(Filters.eq( Restaurant::name.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 deleteMany = DeleteManyModel<Restaurant>(Filters.eq( Restaurant::cuisine.name, "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 insertOneMdl = InsertOneModel(Restaurant("Red's Pizza", "Brooklyn", "Pizzeria")) val updateOneMdl = UpdateOneModel<Restaurant>( Filters.eq(Restaurant::name.name, "Moonlit Tavern"), Updates.set(Restaurant::borough.name, "Queens") ) val deleteManyMdl = DeleteManyModel<Restaurant>( Filters.eq(Restaurant::name.name, "Crepe") ) val bulkResult = collection.bulkWrite( listOf(insertOneMdl, updateOneMdl, deleteManyMdl) ) println(bulkResult)
AcknowledgedBulkWriteResult{insertedCount=1, matchedCount=5, removedCount=3, modifiedCount=2, upserts=[], inserts=[BulkWriteInsert{index=0, id=BsonObjectId{value=...}}]}
Se qualquer uma das operações de gravação falhar, o driver Kotlin Sync 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
Opcionalmente, o método bulkWrite() aceita um parâmetro 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 :
Propriedade | 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 usa a opção ordered(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 opts = BulkWriteOptions().ordered(false) collection.bulkWrite(bulkOperations, opts)
Se alguma das operações de gravação em uma gravação em massa não ordenada falhar, o driver do Kotlin Sync relatará os erros somente depois de 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 BulkWriteResult . Você pode acessar as seguintes informações de uma instância do BulkWriteResult :
Propriedade | 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: