Operaciones de escritura masiva

Datos de muestra

Los ejemplos de esta sección utilizan la restaurants colección sample_restaurants de la base de datos de los conjuntos de datos de muestra de Atlas. Para acceder a esta colección desde su aplicación Scala, cree un MongoClient que se conecte a un clúster de Atlas y asigne los siguientes valores a database las collection variables y:

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

Para aprender cómo crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de ejemplo, consulta la guía MongoDB Get Started.

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 insertOneModel = InsertOneModel(
    Document("name" -> "Blue Moon Grill",
             "borough" -> "Brooklyn",
             "cuisine" -> "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:

• Filtro de query que especifica los criterios utilizados para emparejar documentos en su colección.

• Operación de actualización que desea realizar. Para obtener más información sobre las operaciones de actualización, consulte la guía "Operadores de actualización de campos" en el manual de MongoDB Server.

El siguiente ejemplo crea una instancia de UpdateOneModel:

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

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

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

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

El siguiente ejemplo crea una instancia de UpdateManyModel:

val updateManyFilter = equal("name", "Wendy's")
val updateManyDoc = set("cuisine", "Fast food")
val updateManyModel = UpdateManyModel(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 los siguientes argumentos:

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

• Documento reemplazado que especifica los nuevos campos y valores a insertar

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

Si varios documentos coinciden con el filtro de query especificado en la instancia ReplaceOneModel, la operación reemplaza el primer resultado. Puedes especificar un ordenamiento en una instancia ReplaceOptions 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 = ReplaceOptions.sort(ascending("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 deleteOneModel = DeleteOneModel(equal("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 deleteManyModel = DeleteManyModel(equal("cuisine", "Experimental"))

Realizar la Operación Masiva

Después de definir una instancia de modelo para cada operación que deseas realizar, pasa una instancia Seq que contenga los modelos al método MongoCollection.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 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

Si alguna de las operaciones de escritura falla, el driver de Scala lanzará un BulkWriteError y no realizará ninguna operación adicional. BulkWriteError proporciona un elemento details que incluye la operación que falló y detalles sobre la excepción.

Personalizar escritura masiva

El método MongoCollection.bulkWrite() acepta opcionalmente un parámetro BulkWriteOptions, que especifica las opciones que puedes usar para configurar la operación de guardar masiva. Si no especifica ninguna opción, el driver realiza la operación masiva con la configuración por defecto. Para modificar el comportamiento de la operación de guardado, pasa la instancia de la clase como último argumento al método bulkWrite().

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 establece la opción ordered en false para especificar una escritura masiva desordenada. Luego, el ejemplo usa el método bulkWrite() para realizar una operación masiva:

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

Si alguna de las operaciones de escritura en una escritura en bloque desordenada falla, el driver de Scala informa los errores solo después de intentar todas las operaciones.

Valor de retorno

El método bulkWrite() devuelve un objeto SingleObservable que contiene un BulkWriteResult. Puedes obtener información de la instancia BulkWriteResult suscribiéndote al observable y usando los siguientes métodos:

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 db.people y el otro documento se inserta en la colección db.things. 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 personToInsert = ClientNamespacedWriteModel.insertOne(
  MongoNamespace("db", "people"),
  Document("name" -> "Julia Smith")
)
val thingToInsert = ClientNamespacedWriteModel.insertOne(
  MongoNamespace("db", "things"),
  Document("object" -> "washing machine")
);

Operaciones de actualizar

El siguiente ejemplo muestra cómo utilizar el método bulkWrite() para actualizar documentos existentes en las colecciones db.people y db.things:

val personUpdate = ClientNamespacedWriteModel.updateOne(
  MongoNamespace("db", "people"),
  equal("name", "Freya Polk"),
  inc("age", 1)
)
val thingUpdate = ClientNamespacedWriteModel.updateMany(
  MongoNamespace("db", "things"),
  equal("category", "electronic"),
  set("manufacturer", "Premium Technologies")
)

Este ejemplo incrementa el valor del campo age por 1 en el documento que tiene un valor name de "Freya Polk" en la colección people. También establece el valor del campo manufacturer en "Premium Technologies" en todos los documentos que tienen un valor de category de "electronic" en la colección things.

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

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

Reemplazar operaciones

El siguiente ejemplo muestra cómo crear modelos para reemplazar documentos existentes en las colecciones db.people y db.things:

val personReplacement = ClientNamespacedWriteModel.replaceOne(
  MongoNamespace("db", "people"),
  equal("_id", 1),
  Document("name" -> "Frederic Hilbert")
)
val thingReplacement = ClientNamespacedWriteModel.replaceOne(
  MongoNamespace("db", "things"),
  equal("_id", 1),
  Document("object" -> "potato")
)

El ejemplo de código anterior reemplaza los siguientes documentos con documentos nuevos:

• Documento en la colección people que tiene un valor _id de 1

• Documento en la colección things que tiene un valor _id de 1

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(ascending("_id"))

Realizar la Operación Masiva

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

El siguiente ejemplo realiza múltiples operaciones de escritura usando el método bulkWrite():

val peopleNamespace = MongoNamespace("db", "people")
val thingsNamespace = MongoNamespace("db", "things")
val writeModels = List(
  ClientNamespacedWriteModel.insertOne(
    peopleNamespace,
    Document("name" -> "Corey Kopper")
  ),
  ClientNamespacedWriteModel.replaceOne(
    thingsNamespace,
    equal("_id", 1),
    Document("object" -> "potato")
  )
)
val observable = mongoClient.bulkWrite(writeModels)
observable.subscribe(
  (result: ClientBulkWriteResult) => println(result.toString),
  (error: Throwable) => println(s"Error: ${error.getMessage}"),
  () => println("Completed")
)

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 que se puede acceder mediante el método ClientBulkWriteException.getWriteErrors(), proporcionando información sobre el fallo.

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("db", "people")
val options = ClientBulkWriteOptions.clientBulkWriteOptions().ordered(false)
val writeModels = List(
  ClientNamespacedWriteModel.insertOne(namespace, Document("_id" -> 1, "name" -> "Rudra Suraj")),
  // Causes a duplicate key error
  ClientNamespacedWriteModel.insertOne(namespace, Document("_id" -> 1, "name" -> "Mario Bianchi")),
  ClientNamespacedWriteModel.insertOne(namespace, Document("name" -> "Wendy Zhang"))
)
val observable = mongoClient.bulkWrite(writeModels, options)

Documentación de la API

Para aprender más sobre cualquiera de los métodos o tipos analizados en esta guía, consulta la siguiente documentación de API:

• Guardar masivo de colecciones

  • bulkWrite()

  • InsertOneModel

  • UpdateOneModel

  • ActualizarMuchosModelos

  • ReemplazarUnModelo

  • Eliminar un modelo

  • DeleteManyModel

  • Opciones de escritura masiva

  • BulkWriteResult

• Guardado Masivo del Cliente

  • bulkWrite()

  • Modelo de escritura con espacio de nombres de cliente

  • MongoNamespace

  • ClientBulkWriteOptions

  • ClientBulkWriteResult