/ /

Operaciones de escritura masiva

Overview

En esta guía, puedes aprender a usar el driver Ruby para realizar una operación de guardado en bloque que realice múltiples cambios en tus datos en una sola llamada a la base de datos.

Considera una situación que requiere que insertes documentos, actualices documentos y borres documentos para la misma tarea. Si usas los métodos de guardado individuales, cada operación de guardado accede a la base de datos por separado. En su lugar, puedes usar una operación de escritura masiva para optimizar la cantidad de llamadas que tu aplicación realiza al servidor.

Datos de muestra

Los ejemplos de esta guía utilizan el restaurants colección en la base de datos sample_restaurants de la Conjuntos de datos de muestra de Atlas. Para acceder a esta colección desde su aplicación Ruby, cree un objeto Mongo::Client que se conecte a un clúster Atlas y asigne los siguientes valores a las variables database y collection:

database = client.use('sample_restaurants')
collection = database[: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.

Defina las operaciones de guardado

Para cada operación de guardar que desees realizar, crea un hash que implemente una de las siguientes operaciones.

insert_one
update_one
update_many
replace_one
delete_one
delete_many

Luego, pasa una lista de estas instancias al método bulk_write.

Las siguientes secciones muestran cómo crear y usar instancias de las operaciones anteriores. La sección Realizar la operación masiva demuestra cómo pasar una lista de hashes al método bulk_write para realizar la operación masiva.

Operaciones de inserción

Para realizar una operación de inserción, crea un hash insert_one y especifica el documento que deseas insertar.

El siguiente ejemplo crea un hash insert_one:

insert_one = { insert_one: { name: 'Steve Rogers Cafe', borough: 'Brooklyn' } }

Para insertar varios documentos, cree un hash insert_one separado para cada documento.

Importante

Cuando se realiza una operación masiva, la operación insert_one no puede insertar un documento con un _id que ya existe en la colección. En esta situación, el driver arroja un MongoBulkWriteException.

Operaciones de actualizar

Para actualizar un documento, crea un hash update_one 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, consulta la guía Operadores de actualización de campo en el manual del MongoDB Server.

La update_one operación especifica una actualización para el primer documento que coincida con el filtro de query.

El siguiente ejemplo crea un hash update_one:

update_one = { update_one: 
  { 
    filter: { name: 'Mountain View' },
    update: { '$set': { borough: 'Queens' } }
  }
}

Para actualizar varios documentos, crea un hash update_many y pasa los mismos argumentos que en una operación update_one. La update_many operación especifica actualizaciones para todos los documentos que coinciden con tu filtro de query.

El siguiente ejemplo crea un hash update_many:

update_many = { update_many: 
  { 
    filter: { name: 'Starbucks' },
    update: { '$set': { cuisine: 'Cafe' } }
  }
}

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 un hash replace_one 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 un hash de replace_one:

replace_one = { replace_one:
  { 
    filter: { name: 'Old World Diner' },
    replacement: { '$set': { name: 'New Age Luncheonette' } }
  }
}

Para reemplazar varios documentos, debe crear un hash replace_one para cada documento.

Operaciones de borrar

Para eliminar un documento, cree un delete_one hash y pase un filtro de consulta que especifique el documento que desea eliminar. La delete_one operación elimina solo el primer documento que coincida con el filtro de consulta.

El siguiente ejemplo crea un hash de delete_one:

delete_one = { delete_one: { name: 'Old World Diner' } }

Para eliminar múltiples documentos, crea un delete_many hash y pasa un filtro de query especificando el documento que deseas eliminar. La delete_many operación borra todos los documentos que coinciden con tu filtro de query.

El siguiente ejemplo crea un hash de delete_many:

delete_many = { delete_many: { name: 'Starbucks' } }

Realizar la Operación Masiva

Después de definir una hash para cada operación que desee realizar, pase una lista de estos objetos al método bulk_write. Por defecto, el método ejecuta las operaciones en el orden especificado por la lista de hashes.

El siguiente ejemplo realiza múltiples operaciones de escritura usando el método bulk_write:

insert_one = { insert_one: { name: 'Nuovo Ristorante', borough: 'Brooklyn', cuisine: 'Italian' } }
update_one = { update_one: 
  { 
    filter: { name: 'Moonlit Tavern' },
    update: { '$set': { borough: 'Queens' } }
  }
}
delete_many = { delete_many: { name: 'Crepe' } }
writes = [insert_one, update_one, delete_many]
collection.bulk_write(writes)

Si falla alguna de las operaciones de guardar, el controlador de Ruby genera un BulkWriteError y no realiza ninguna otra operación. BulkWriteError proporciona un elemento details que incluye la operación que falló y detalles sobre la excepción.

Nota

Cuando el controlador ejecuta una operación masiva, utiliza la preocupación de escritura de la colección de destino. El controlador informa todos los errores de preocupación de escritura después de intentar todas las operaciones, independientemente del orden de ejecución.

Personalizar la operación de escritura masiva

El método bulk_write acepta opcionalmente un hash options que especifica opciones que se pueden 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 las opciones que puede utilizar para configurar el método bulk_write:

Opción	Descripción
`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`.
`bypass_document_validation`	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`.
`session`	The session to use for the operation. Type: `Session`
`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.

El siguiente código crea opciones y establece la opción ordered en false para especificar una escritura masiva desordenada. A continuación, el código utiliza el método bulk_write para realizar las mismas operaciones masivas que en el ejemplo anterior:

options = { ordered: false }
collection.bulk_write(writes, options)

Si alguna de las operaciones de guardar en una guardar masiva desordenada falla, el driver Ruby informa de los errores solo después de intentar todas las operaciones.

Nota

Las operaciones masivas desordenadas no garantizan un orden de ejecución. El orden puede variar según la forma en que se enumeran para optimizar el tiempo de ejecución.

Valor de retorno

El método bulk_write retorna un BulkWrite::Result. Puedes acceder a la información de la instancia Result usando los siguientes métodos de instancia:

Método	Descripción
`acknowledged?`	Indicates if the server acknowledged the write operation.
`deleted_count`	Returns the number of documents deleted, if any.
`inserted_count`	Returns the number of documents inserted, if any.
`inserted_ids`	Returns the list of inserted document ids, if any.
`matched_count`	Returns the number of documents matched for an update, if applicable.
`modified_count`	Returns the number of documents modified, if any.
`upserted_count`	Returns the number of upserted documents, if any.
`upserted_ids`	Returns the list of upserted document ids, if any.

Información Adicional

Para aprender cómo realizar operaciones de guardar individuales, consulta los siguientes guías:

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:

Volver

Delete Documents

Transacciones