Operaciones de escritura masiva

Datos de muestra

Los ejemplos de esta guía utilizan las colecciones sample_restaurants.restaurants y sample_mflix.movies del Atlas datasets de muestra. Para aprender a crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de muestra, consulta Comienza con Atlas.

Los documentos de estas colecciones están modelados por las siguientes clases de datos de Kotlin:

data class Restaurant(
    val name: String,
    val borough: String,
    val cuisine: String,
    val stars: Int? = null,
)
data class Movie(
    val title: String,
    val year: Int,
    val seen: Boolean? = null,
)

Operaciones de inserción

Para realizar una operación de inserción, cree una instancia InsertOneModel y especifique el documento que desea insertar.

El siguiente ejemplo crea una instancia de InsertOneModel:

val blueMoon = InsertOneModel(Restaurant("Blue Moon Grill", "Brooklyn", "American"))

Para insertar varios documentos, cree una instancia de InsertOneModel para cada documento.

Operaciones de actualizar

Para actualizar un documento, crea una instancia de UpdateOneModel y pasa los siguientes argumentos:

• Un filtro de query que especifica los criterios utilizados para hacer coincidir documentos en tu colección

• La operación de actualizar que deseas realizar. Para obtener más información sobre los operadores de actualización, consulta la guía de Operadores de actualización de campos en el manual de MongoDB Server.

Una UpdateOneModel instancia especifica una actualización para el primer documento que coincide con su filtro de consulta.

El siguiente ejemplo crea una instancia 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)

Si varios documentos coinciden con el filtro de query especificado en la instancia UpdateOneModel, la operación actualiza el primer resultado. Puedes especificar un ordenamiento en una instancia UpdateOptions para aplicar un orden a los documentos coincidentes antes de que el servidor realice la operación de actualización, como se muestra en el siguiente código:

val opts = UpdateOptions().sort(Sorts.ascending(Restaurant::name.name))

Para actualizar varios documentos, cree una instancia de UpdateManyModel y pase los mismos argumentos que para UpdateOneModel. La clase UpdateManyModel especifica actualizaciones para todos los documentos que coincidan con su filtro de query.

El siguiente ejemplo crea una instancia de UpdateManyModel para indicar al controlador que actualice todos los documentos coincidentes:

val updateManyFilter = Filters.eq(Restaurant::name.name, "Wendy's")
val updateManyDoc = Updates.set(Restaurant::cuisine.name, "Fast food")
val wendysUpdate = UpdateManyModel<Restaurant>(updateManyFilter, updateManyDoc)

Reemplazar operaciones

Una operación de reemplazo remueve todos los campos y valores de un documento especificado y los reemplaza por nuevos campos y valores que usted especifica. Para realizar una operación de reemplazo, crea una instancia de ReplaceOneModel y pasa un filtro de query junto con los campos y valores con los que deseas reemplazar el documento coincidente.

El siguiente ejemplo crea una instancia 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)

Si varios documentos coinciden con el filtro de query especificado en la instancia ReplaceOneModel, la operación reemplaza el primer resultado. Puedes especificar una medida en una instancia ReplaceOptions para aplicar un orden a los documentos coincidentes antes de que el servidor realice la operación de reemplazo, como se muestra en el siguiente código:

val opts = ReplaceOptions().sort(Sorts.ascending(Restaurant::name.name))

Operaciones de borrar

Para borrar un documento, crea una instancia de DeleteOneModel y pasa un filtro de query que especifique el documento que deseas borrar. Una instancia DeleteOneModel proporciona instrucciones para eliminar solo el primer documento que coincida con tu filtro de query.

El siguiente ejemplo crea una instancia de DeleteOneModel:

val deleteOne = DeleteOneModel<Restaurant>(Filters.eq(
    Restaurant::name.name,
    "Morris Park Bake Shop"
))

Para borrar varios documentos, cree una instancia de DeleteManyModel y pase un filtro de query que especifique el documento que desea borrar. Una instancia de DeleteManyModel proporciona instrucciones para remover todos los documentos que coincidan con el filtro de query.

El siguiente ejemplo crea una instancia de DeleteManyModel:

val deleteMany = DeleteManyModel<Restaurant>(Filters.eq(
    Restaurant::cuisine.name,
    "Experimental"
))

Realizar la Operación Masiva

Después de definir una instancia de modelo para cada operación que desees realizar, pasa una lista de estas instancias al método bulkWrite(). Por defecto, el método ejecuta las operaciones en el orden especificado por la lista de modelos.

El siguiente ejemplo realiza múltiples operaciones de escritura usando el 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=...}}]}

Si alguna de las operaciones de guardado falla, el driver de sincronización de Kotlin genera un BulkWriteError y no realiza ninguna operación adicional. BulkWriteError proporciona un campo details que incluye la operación que falló y detalles sobre la excepción.

Personalizar la operación de escritura masiva

El método bulkWrite() acepta opcionalmente un parámetro que especifica las opciones que puedes usar para configurar la operación de escritura masiva. Si no especifica ninguna opción, el driver realiza la operación masiva con la configuración por defecto.

La siguiente tabla describe los métodos de establecimiento que puedes utilizar para configurar una instancia de BulkWriteOptions:

El siguiente código crea opciones y usa la opción ordered(false) para especificar una escritura masiva desordenada. Luego, el ejemplo usa el método bulkWrite() para realizar una operación masiva:

val opts = BulkWriteOptions().ordered(false)
collection.bulkWrite(bulkOperations, opts)

Si alguna de las operaciones de guardado en una escritura masiva desordenada falla, el controlador de Kotlin sincronizar informa los errores solo después de intentar todas las operaciones.

Valor de retorno

El método bulkWrite() devuelve un objeto BulkWriteResult. Puede acceder a la siguiente información desde una instancia BulkWriteResult:

Operaciones de inserción

Este ejemplo muestra cómo crear modelos que contienen instrucciones para insertar dos documentos. Un documento se inserta en la colección sample_restaurants.restaurants y el otro documento se inserta en la colección sample_mflix.movies. La instancia MongoNamespace define la base de datos y la colección de destino a las que se aplica cada operación de guardar.

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

Operación de actualización

El siguiente ejemplo muestra cómo utilizar el método bulkWrite() para actualizar documentos existentes en las colecciones sample_restaurants.restaurants y sample_mflix.movies:

val restaurantUpdate = ClientNamespacedWriteModel
    .updateOne(
        MongoNamespace("sample_restaurants", "restaurants"),
        Filters.eq(Restaurant::name.name, "Villa Berulia"),
        Updates.inc(Restaurant::stars.name, 1)
    )
val movieUpdate = ClientNamespacedWriteModel
    .updateMany(
        MongoNamespace("sample_mflix", "movies"),
        Filters.eq(Movie::title.name, "Carrie"),
        Updates.set(Movie::seen.name, true)
    )

Este ejemplo incrementa el valor del campo stars por 1 en el documento que tiene un valor name de "Villa Berulia" en la colección restaurants. También establece el valor del campo seen en true en todos los documentos que tienen un valor de title de "Carrie" en la colección movies.

Si varios documentos coinciden con el filtro de consulta especificado en una ClientNamespacedUpdateOneModel instancia, la operación actualiza el primer resultado. Puede especificar un orden de clasificación en una instancia ClientUpdateOneOptions para aplicarlo a los documentos coincidentes antes de que el servidor realice la operación de actualización, como se muestra en el siguiente código:

val options =  ClientUpdateOneOptions
    .clientUpdateOneOptions()
    .sort(Sorts.ascending("_id"))

Reemplazar operaciones

El siguiente ejemplo muestra cómo crear modelos para reemplazar documentos existentes en las colecciones sample_restaurants.restaurants y sample_mflix.movies:

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

Después de que este ejemplo se ejecute correctamente, el documento que tiene un valor _id de 1 en la colección restaurants es reemplazado por un nuevo documento. El documento en la colección movies que tiene un valor _id de 1 también se reemplaza por un nuevo documento.

Si varios documentos coinciden con el filtro de query especificado en una instancia de ClientNamespacedReplaceOneModel, la operación reemplaza el primer resultado. Se puede especificar un orden de clasificación en una instancia de ClientReplaceOneOptions para aplicar un orden a los documentos coincidentes antes de que el driver realice la operación de reemplazo, como se muestra en el siguiente código:

val options =  ClientReplaceOneOptions
    .clientReplaceOneOptions()
    .sort(Sorts.ascending("_id"))

Realizar la Operación Masiva

Después de definir una instancia de ClientNamespacedWriteModel para cada operación que desee realizar, pase una lista de estas instancias al método del cliente bulkWrite(). Por defecto, el método ejecuta las operaciones en el orden en que se especifican.

El siguiente ejemplo realiza múltiples operaciones de escritura usando el 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, ...}

Si cualquiera de las operaciones de escritura falla, el driver genera un ClientBulkWriteException y no realiza ninguna otra operación individual. ClientBulkWriteException incluye un BulkWriteError al cual se puede acceder utilizando el método ClientBulkWriteException.getWriteErrors(), que proporciona detalles de la falla individual.

Personalizar escritura masiva

Puede pasar una instancia de ClientBulkWriteOptions al método bulkWrite() para personalizar cómo el controlador ejecuta la operación de escritura masiva.

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)

Documentación de la API

Para obtener más información sobre cualquiera de los métodos o tipos discutidos en esta guía, consultar la siguiente documentación de la API:

• Guardar masivo de colecciones

  • bulkWrite()

  • InsertOneModel

  • UpdateOneModel

  • ActualizarMuchosModelos

  • ReemplazarUnModelo

  • Eliminar un modelo

  • DeleteManyModel

  • BulkWriteResult

  • Error de escritura masiva

  • MongoBulkWriteException

• Guardado Masivo del Cliente

  • bulkWrite()

  • Modelo de escritura con espacio de nombres de cliente

  • MongoNamespace

  • ClientBulkWriteOptions

  • ClientBulkWriteResult