Operaciones de escritura masiva

Overview

En esta guía, puedes aprender a realizar múltiples operaciones de escritura en una sola llamada a la base de datos utilizando operaciones de escritura en bloque.

Imagine un escenario en el que desea insertar un documento en una colección, actualizar varios documentos y, finalmente, eliminar un documento. Si utiliza funciones individuales, cada operación requiere su propia llamada a la base de datos. En su lugar, puede usar una operación masiva para reducir el número de llamadas a la base de datos.

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 aprender a crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de ejemplo, consulta la guía Introducción a MongoDB.

Iniciar la operación de escritura masiva

Antes de ejecutar una operación de escritura masiva, llama la función mongoc_collection_create_bulk_operation_with_opts(). Esta función devuelve un valor de tipo mongoc_bulk_operation_t que puede usar para almacenar instrucciones sobre qué escrituras masivas realizar.

La función mongoc_collection_create_bulk_operation_with_opts() acepta los siguientes parámetros:

Colección: Especifica la colección a modificar
Documento de opciones: Especifica opciones para personalizar la operación, o NULL

El siguiente ejemplo llama a la función mongoc_collection_create_bulk_operation_with_opts() y pasa la colección restaurants como un parámetro:

mongoc_bulk_operation_t *bulk =
   mongoc_collection_create_bulk_operation_with_opts(collection, NULL);

Luego puedes agregar instrucciones para guardar a la operación masiva. Para obtener más información, consulta la siguiente sección Definición de las operaciones de guardado.

Defina las operaciones de guardado

Puede definir una operación de escritura y agregarla a la escritura masiva llamando a los siguientes métodos:

mongoc_bulk_operation_insert_with_opts()
mongoc_bulk_operation_update_one_with_opts()
mongoc_bulk_operation_update_many_with_opts()
mongoc_bulk_operation_replace_one_with_opts()
mongoc_bulk_operation_remove_one_with_opts()
mongoc_bulk_operation_remove_many_with_opts()

Las siguientes secciones muestran cómo utilizar estos métodos para especificar sus operaciones de escritura correspondientes.

Operaciones de inserción

Para realizar una operación de inserción, agregue las instrucciones de inserción a la mongoc_bulk_operation_t, que pone en cola la operación como parte de la escritura masiva.

El siguiente ejemplo llama a la función mongoc_bulk_operation_insert_with_opts(), pasando el documento a insertar y el valor mongoc_bulk_operation_t como parámetros:

bson_t *insert_doc = BCON_NEW(
    "name", BCON_UTF8("Mongo's Deli"),
    "cuisine", BCON_UTF8("Sandwiches"),
    "borough", BCON_UTF8("Manhattan"),
    "restaurant_id", BCON_UTF8("1234")
);
bson_error_t error;
if (!mongoc_bulk_operation_insert_with_opts(bulk, insert_doc, NULL, &error)) {
    fprintf(stderr, "Failed to add insert operation: %s\n", error.message);
}
bson_destroy(insert_doc);

Para insertar varios documentos, llame a mongoc_bulk_operation_insert_with_opts() para cada documento.

Operaciones de actualizar

Para realizar una operación de actualización, agrega las instrucciones de actualización al mongoc_bulk_operation_t, que pone en cola la operación como parte de la escritura masiva.

El siguiente ejemplo llama a la función mongoc_bulk_operation_update_one_with_opts(), pasando un filtro de consulta, actualizaciones de documentos y el valor mongoc_bulk_operation_t como parámetros:

bson_t *filter_doc = BCON_NEW("name", BCON_UTF8("Mongo's Deli"));
bson_t *update_doc = BCON_NEW("$set", "{", "cuisine", BCON_UTF8("Sandwiches and Salads"), "}");
bson_error_t error;
if (!mongoc_bulk_operation_update_one_with_opts(bulk, filter_doc, update_doc, NULL, &error)) {
    fprintf(stderr, "Failed to add update operation: %s\n", error.message);
}
bson_destroy(filter_doc);
bson_destroy(update_doc);

Para actualizar varios documentos, llama a mongoc_bulk_operation_update_many_with_opts() y pasa los mismos parámetros. Esto le indica al driver que actualice todos los documentos que coincidan con su filtro de query.

El siguiente ejemplo pone en cola una operación de actualizar varios para la escritura por lotes:

bson_t *filter_doc = BCON_NEW("name", BCON_UTF8("Mongo's Deli"));
bson_t *update_doc = BCON_NEW("$set", "{", "cuisine", BCON_UTF8("Sandwiches and Salads"), "}");
bson_error_t error;
if (!mongoc_bulk_operation_update_many_with_opts(bulk, filter_doc, update_doc, NULL, &error)) {
    fprintf(stderr, "Failed to add update operation: %s\n", error.message);
}
bson_destroy(filter_doc);
bson_destroy(update_doc);

Reemplazar operaciones

Una operación de reemplazo remueve todos los campos y valores de un documento especificado y los reemplaza por otros nuevos. Para realizar una operación de reemplazo, añade las instrucciones de reemplazo a la mongoc_bulk_operation_t, que pone en cola la operación como parte de la escritura masiva.

El siguiente ejemplo llama la función mongoc_bulk_operation_replace_one_with_opts(), pasando un filtro de query, un documento de reemplazo y el valor mongoc_bulk_operation_t como parámetros:

bson_t *filter_doc = BCON_NEW("restaurant_id", BCON_UTF8("1234"));
bson_t *replace_doc = BCON_NEW(
    "name", BCON_UTF8("Mongo's Deli"),
    "cuisine", BCON_UTF8("Sandwiches and Salads"),
    "borough", BCON_UTF8("Brooklyn"),
    "restaurant_id", BCON_UTF8("5678")
);
bson_error_t error;
if (!mongoc_bulk_operation_replace_one_with_opts(bulk, filter_doc, replace_doc, NULL, &error)) {
    fprintf(stderr, "Failed to add replace operation: %s\n", error.message);
}
bson_destroy(filter_doc);
bson_destroy(replace_doc);

Para reemplazar varios documentos, llama a mongoc_bulk_operation_replace_one_with_opts() por cada documento.

Operaciones de borrar

Para realizar una operación de borrado, agrega las instrucciones de borrado al mongoc_bulk_operation_t, que pone en cola la operación como parte del guardado masivo.

El siguiente ejemplo llama a la función mongoc_bulk_operation_remove_one_with_opts(), pasando un filtro de query y el valor mongoc_bulk_operation_t como parámetros:

bson_t *filter_doc = BCON_NEW("restaurant_id", BCON_UTF8("5678"));
bson_error_t error;
if (!mongoc_bulk_operation_remove_one_with_opts(bulk, filter_doc, NULL, &error)) {
    fprintf(stderr, "Failed to add delete operation: %s\n", error.message);
}
bson_destroy(filter_doc);

Para borrar varios documentos, llama a la función mongoc_bulk_operation_remove_many_with_opts() y pasa los mismos parámetros. Esto indica al driver que borre todos los documentos que coincidan con tu filtro de query.

El siguiente ejemplo incorpora la operación de borrado masivo al guardado masivo:

bson_t *filter_doc = BCON_NEW("borough", BCON_UTF8("Manhattan"));
bson_error_t error;
if (!mongoc_bulk_operation_remove_many_with_opts(bulk, filter_doc, NULL, &error)) {
    fprintf(stderr, "Failed to add delete operation: %s\n", error.message);
}
bson_destroy(filter_doc);

Ejecutar la operación masiva

Para ejecutar cada operación de escritura en cola en la escritura masiva, llame a la función mongoc_bulk_operation_execute(). Esta función acepta los siguientes parámetros:

valor mongoc_bulk_operation_t: Contiene las instrucciones para cada operación de guardar
Ubicación de los resultados: Especifica un puntero a un almacenamiento sobrescribible que contendrá los resultados de la operación o NULL
Ubicación del error: Especifica una ubicación para un valor de error o NULL

Utiliza la siguiente sintaxis para guardar documentos en masa:

bson_error_t error;
mongoc_bulk_operation_t *bulk =
   mongoc_collection_create_bulk_operation_with_opts(collection, NULL);
bson_t *insert_doc = BCON_NEW(
    "<field name>", BCON_UTF8("<value>"),
    "<field name>", BCON_UTF8("<value>"),
    "<field name>", BCON_UTF8("<value>"),
    "<field name>", BCON_UTF8("<value>")
);
mongoc_bulk_operation_insert(bulk, insert_doc);
bson_destroy(insert_doc);
    
bson_t *query = BCON_NEW("<field to match>", BCON_UTF8("<value to match>"));
bson_t *update = BCON_NEW("$set", "{", "<field name>", BCON_UTF8("<value>"), "}");
mongoc_bulk_operation_update_one(bulk, query, update, false);
bson_destroy(query);
bson_destroy(update);
bool result = mongoc_bulk_operation_execute(bulk, NULL, &error);
if (!result) {
    fprintf(stderr, "Bulk operation error: %s\n", error.message);
}
mongoc_bulk_operation_destroy(bulk);

El siguiente ejemplo realiza las operaciones de inserción, actualización, reemplazo, y eliminación especificadas en las secciones anteriores de esta guía llamando a la función mongoc_bulk_operation_execute():

bson_error_t error;
bool result = mongoc_bulk_operation_execute(bulk, NULL, &error);
if (!result) {
    printf("Bulk operation error: %s\n", error.message);
}
mongoc_bulk_operation_destroy(bulk);

Si alguna de las operaciones de escritura falla, el controlador C establece el error de salida y no realiza ninguna operación adicional.

Personaliza las operaciones de escritura masiva

Puedes modificar el comportamiento de la función mongoc_collection_create_bulk_operation_with_opts() pasando un documento BSON que especifique los valores de opción. La siguiente tabla describe las opciones que puede configurar en el documento:

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`.
`writeConcern`	Specifies the write concern for the bulk operation. For more information, see Write Concern in the MongoDB Server manual.
`sessionId`	Runs the bulk operations within the specified session. For more information, see Server Sessions in the MongoDB Server manual.
`comment`	Attaches a comment to the operation. For more information, see the delete command fields guide in the MongoDB Server manual.
`let`	Specifies a document with a list of values to improve operation readability. Values must be constant or closed expressions that don't reference document fields. For more information, see the let statement in the MongoDB Server manual.

El siguiente ejemplo llama a la función mongoc_collection_create_bulk_operation_with_opts() y establece la opción ordered en false:

bson_t opts;
BSON_APPEND_BOOL(&opts, "ordered", false);
bulk = mongoc_collection_create_bulk_operation_with_opts(collection, &opts);
// Perform bulk operation
bson_destroy(&opts);
mongoc_bulk_operation_destroy(bulk);

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

Nota

Las operaciones masivas no ordenadas no ofrecen garantías del orden de ejecución. El orden puede diferir de la manera en que los enumeras para optimizar el tiempo de ejecución.

Información Adicional

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

Documentación de la API

Para obtener más información sobre cualquiera de las funciones o tipos analizados en esta guía, consulte la siguiente documentación de API:

Volver

Borrar

Transacciones