Operações de gravação em massa

Dados de amostra

Os exemplos neste guia usam as sample_restaurants.restaurants sample_mflix.movies collections e 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 nessas collections são modelados pelas seguintes classes de dados do Kotlin :

data class Restaurant(
    val name: String,
    val borough: String,
    val cuisine: String
)
data class Movie(
    val title: String,
    val year: Int
)

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.

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 operadores 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)

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 opts = UpdateOptions().sort(Sorts.ascending(Restaurant::name.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 seguinte cria uma instância de UpdateManyModel para direcionar o driver para atualizar todos os documentos correspondentes:

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)

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 opts = ReplaceOptions().sort(Sorts.ascending(Restaurant::name.name))

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 campo details que inclui a operação que falhou e detalhes sobre a exceçã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 :

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.

Valor de retorno

O método bulkWrite() retorna um objeto BulkWriteResult . Você pode acessar as seguintes informações de uma instância do BulkWriteResult :

Inserir operações

Este exemplo mostra como criar modelos que contêm instruções para inserir dois documentos. Um documento é inserido na collection db.people e o outro documento é inserido na collection db.things. A instância MongoNamespace define o banco de dados de destino e a collection à qual cada operação de gravação se aplica.

val restaurantToInsert = ClientNamespacedWriteModel
    .insertOne(
        MongoNamespace("sample_restaurants", "restaurants"),
        Restaurant("Blue Moon Grill", "Brooklyn", "American")
    )
val movieToInsert = ClientNamespacedWriteModel
    .insertOne(
        MongoNamespace("sample_mflix", "movies"),
        Movie("Silly Days", 2022)
    )

Operações de substituição

O exemplo a seguir mostra como criar modelos para substituir documentos existentes nas coleções db.people e db.things:

val restaurantReplacement = ClientNamespacedWriteModel
    .replaceOne(
        MongoNamespace("sample_restaurants", "restaurants"),
        Filters.eq("_id", 1),
        Restaurant("Smith Town Diner", "Brooklyn", "American")
    )
val movieReplacement = ClientNamespacedWriteModel
    .replaceOne(
        MongoNamespace("sample_mflix", "movies"),
        Filters.eq("_id", 1),
        Movie("Loving Sylvie", 1999)
    )

Depois que esse exemplo for executado com êxito, o documento que tem um valor _id de 1 na coleção people é substituído por um novo documento. O documento na coleção things que tem um valor _id de 1 é substituído por um novo documento.

Executar a operação em massa

Depois de definir uma instância ClientNamespacedWriteModel para cada operação que deseja executar, passe uma lista dessas instâncias para o método bulkWrite() do cliente . Por padrão, o método executa as operações na ordem em que são especificadas.

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

val restaurantNamespace = MongoNamespace("sample_restaurants", "restaurants")
val movieNamespace = MongoNamespace("sample_mflix", "movies")
val bulkOperations = listOf(
    ClientNamespacedWriteModel
        .insertOne(
            restaurantNamespace,
            Restaurant("Drea's", "Brooklyn", "Mexican")
        ),
    ClientNamespacedWriteModel
        .replaceOne(
            movieNamespace,
            Filters.eq("_id", 1),
            Movie("Underneath It All", 2002)
        )
)
val clientBulkResult = mongoClient
    .bulkWrite(bulkOperations)
println(clientBulkResult.toString())

AcknowledgedSummaryClientBulkWriteResult{insertedCount=1, matchedCount=1, ...}

Se qualquer uma das operações de gravação falhar, o driver emitirá um ClientBulkWriteException e não executará mais nenhuma operação individual. ClientBulkWriteException inclui um BulkWriteError que pode ser acessado usando o método ClientBulkWriteException.getWriteErrors() , que fornece detalhes da falha individual.

Personalizar escrita em massa

Você pode passar uma instância de ClientBulkWriteOptions para o método bulkWrite() para personalizar como o driver executa a operação de gravação em massa.

val namespace = MongoNamespace("sample_restaurants", "restaurants")
val options = ClientBulkWriteOptions
    .clientBulkWriteOptions()
    .ordered(false)
val bulkOps = listOf(
    ClientNamespacedWriteModel.insertOne(
        namespace,
        Document("_id", 1).append("name", "Freezyland")
    ),
    // Causes a duplicate key error
    ClientNamespacedWriteModel.insertOne(
        namespace,
        Document("_id", 1).append("name", "Coffee Stand No. 1")
    ),
    ClientNamespacedWriteModel.insertOne<Any>(
        namespace,
        Document("name", "Kelly's Krepes")
    )
)
val result= mongoClient
    .bulkWrite(bulkOps, options)

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:

• Gravação em massa de collections

  • bulkWrite()

  • InsertOneModel

  • UpdateOneModel

  • UpdateManyModel

  • ReplaceOneModel

  • DeleteOneModel

  • DeleteManyModel

  • BulkWriteResult

  • BulkWriteError

  • MongoBulkWriteException

• Gravação em massa do cliente

  • bulkWrite()

  • ClientNamespacedWriteModel

  • MongoNamespace

  • ClientBulkWriteOptions

  • ClientBulkWriteResult