/ /

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 la colección restaurants en la base de datos sample_restaurants de los conjuntos de datos de muestra de Atlas. Para acceder a esta colección desde tu aplicación Ruby, crea un objeto Mongo::Client que se conecte a un clúster de Atlas y asigna los siguientes valores a tus 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 múltiples 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 borrar un documento, crea un delete_one hash y pasa un filtro de query que especifique el documento que quieres borrar. La delete_one operación borra únicamente el primer documento que coincide con tu filtro de query.

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 driver ejecuta una operación masiva, utiliza el nivel de confirmación de escritura (write concern) de la colección de destino. El driver reporta todos los errores de nivel de confirmación de escritura (write concern) después de intentar todas las operaciones, independientemente del orden de ejecución.

Personalizar la operación de guardar 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`	Si `true`, el driver realiza las operaciones de guardado en el orden proporcionado. Si se produce un error, no se intentarán las operaciones restantes. Si `false`, el driver realiza las operaciones en un orden arbitrario e intenta realizar todas las operaciones. Se establece por defecto en `true`.
`bypass_document_validation`	Especifica si la operación de actualización omite la validación del documento. Esto permite actualizar documentos que no cumplen con los requisitos de validación del esquema, si los hubiera. Para obtener más información sobre la validación del esquema, consulte Validación de esquema en el manual del servidor MongoDB. El valor predeterminado `false` es.
`session`	La sesión que se utilizará para la operación. Tipo: `Session`
`let`	Proporciona un mapa de nombres y valores de parámetros para establecer variables de nivel superior para la operación. Los valores deben ser constantes o expresiones cerradas que no hagan referencia a campos del documento.

El siguiente código crea opciones y establece la opción ordered en false para especificar una escritura masiva no ordenada. Luego, 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 no ordenadas no garantizan el orden de ejecución. El orden puede diferir del modo en que los enumere 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?`	Indica si el servidor reconoció la operación de guardado.
`deleted_count`	Devuelve el número de documentos borrados, si los hay.
`inserted_count`	Devuelve el número de documentos insertados, si los hay.
`inserted_ids`	Devuelve la lista de identificadores de documentos insertados, si los hay.
`matched_count`	Devuelve el número de documentos coincidentes para una actualización, si corresponde.
`modified_count`	Devuelve el número de documentos modificados, si los hay.
`upserted_count`	Devuelve el número de documentos insertados o actualizados, si los hay.
`upserted_ids`	Devuelve la lista de identificadores de documentos insertados o actualizados, si los hay.

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