/ /

Reemplazar Documentos

Overview

En esta guía, puedes aprender cómo utilizar el controlador C++ para ejecutar una operación de reemplazo en una colección de MongoDB. Una operación de reemplazo remueve todos los campos excepto el campo _id en el documento de destino y los reemplaza con nuevos campos. Puedes llamar al método replace_one() para reemplazar un solo documento.

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 en C++, instancia un mongocxx::client que se conecte a un clúster Atlas y asigna los siguientes valores a tus variables db y collection:

auto db = client["sample_restaurants"];
auto collection = db["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.

Operación de reemplazo

Se puede realizar una operación de reemplazo llamando al método replace_one(). Este método elimina todos los campos excepto el campo _id del primer documento que coincide con los criterios de búsqueda. Luego inserta en el documento los campos y valores que especifiques.

El método replace_one() requiere los siguientes parámetros:

Documento de filtro de query: Especifica qué documento reemplazar. Para obtener más información sobre los filtros de query, consulta Documentos de filtros de query en el manual de MongoDB Server.
Reemplazar documento: Especifica los campos y valores a insertar en el nuevo documento.

Importante

Los valores de los campos _id son inmutables. Si tu documento de reemplazo especifica un valor para el campo _id, este debe coincidir con el valor _id del documento existente.

Ejemplo de reemplazo de un documento

El siguiente ejemplo utiliza el método replace_one() para reemplazar un documento que tiene un valor de campo name de "Nobu" con un nuevo documento que tiene un valor de campo name de "La Bernadin":

auto query_filter = make_document(kvp("name", "Nobu"));
auto replace_doc = make_document(kvp("name", "La Bernadin"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view());

Para comprobar si reemplazaste con éxito el documento, puedes usar el método find_one() para imprimir el nuevo documento:

auto new_doc = collection.find_one(make_document(kvp("name", "La Bernadin")));
std::cout << "New document: " << bsoncxx::to_json(*new_doc) << std::endl;

New document: { "_id" : { "$oid" : "..." }, "name" : "La Bernadin" }

Para obtener más información sobre el método find_one(), consulta encontrar un documento en la guía de Recuperar datos.

opciones

Se puede modificar el comportamiento del método replace_one() pasando una instancia de la clase mongocxx::options::replace como un argumento opcional. La siguiente tabla describe los campos que puedes establecer en una instancia de mongocxx::options::replace:

Campo	Descripción
`bypass_document_validation`	Especifica si la operación de reemplazo omite la validación del documento. Si `true` se establece en, permite reemplazar un documento por otro nuevo que no cumple con los requisitos de validación del esquema. Para obtener más información, consulte Validación de esquema en el manual del servidor MongoDB. El valor predeterminado `false` es.
`collation`	Especifica el tipo de intercalación de lenguaje a usar al ordenar los resultados. Para obtener más información, consulte intercalación en el manual de MongoDB Server.
`comment`	Especifica un comentario de cualquier tipo válido de BSON para adjuntar a la operación. Una vez definido, este comentario aparece junto con los registros de este comando en las siguientes ubicaciones: mensajes de registro de mongod, en el campo `attr.command.cursor.comment` Salidas del perfilador de base de datos, en el campo `system.profile.command` `comment` `currentOp` salida, en el campo `currentOp.command` `comment` Para obtener más información, consulte la guía de Campos de Comando de inserción en el manual del MongoDB Server.
`hint`	Especifica el índice que se va a escanear para encontrar documents que coincidan con el filtro de query. Para obtener más información, consulte el campo de sugerencia en el manual del MongoDB Server.
`let`	Especifica un document que contiene variables y sus valores para ser utilizados en el método `replace_one()`. Esto permite mejorar la legibilidad del código separando las variables del texto de la operación. Los valores deben ser constantes o expresiones cerradas que no hagan referencia a los campos del document. Para obtener más información, consulta el campo let en el manual de MongoDB Server.
`upsert`	Especifica si la operación de reemplazo realiza una operación de inserción/actualización si ningún documento coincide con el filtro de consulta. El valor predeterminado `false` es.
`write_concern`	Establece el nivel de confirmación de escritura (write concern) para la operación. Para más información, consulta nivel de confirmación de escritura (Write Concern) en el manual de MongoDB Server.

Ejemplo: Opción hint

El siguiente ejemplo utiliza el método create_index() para crear un índice ascendente de un solo campo en el campo name. Luego pasa un objeto mongocxx::options::replace al método replace_one() después de establecer su campo hint en el nuevo índice. Esto instruye a la operación de reemplazo para que busque en el índice de campo name al reemplazar un documento que tenga un valor de campo name de "Nobu":

auto index_specification = make_document(kvp("name", 1));
collection.create_index(index_specification.view());
mongocxx::options::replace opts{}; 
opts.hint(mongocxx::hint{"name_1"});
auto query_filter = make_document(kvp("name", "Nobu"));
auto replace_doc = make_document(kvp("name", "La Bernadin"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view(), opts);

Para aprender más sobre los índices, consulta la guía Optimiza consultas con índices.

Ejemplo: opción de actualización e inserción

El siguiente ejemplo pasa un objeto mongocxx::options::replace al método replace_one() después de establecer el valor de su campo upsert en true. Dado que ningún documento coincide con el filtro de query, esto le indica a la operación de reemplazo que inserte un nuevo documento con un valor de campo name de "Shake Shack" en la colección:

std::cout << "Total document count before replace_one(): " << collection.count_documents({}) << std::endl;
mongocxx::options::replace opts{}; 
opts.upsert(true);
auto query_filter = make_document(kvp("name", "In-N-Out Burger"));
auto replace_doc = make_document(kvp("name", "Shake Shack"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view(), opts);
std::cout << "Total document count after replace_one(): " << collection.count_documents({}) << std::endl;

Total document count before replace_one(): 25359
Total document count after replace_one(): 25360

Valor de retorno

El método replace_one() retorna una instancia de la clase mongocxx::result::replace. Esta clase contiene las siguientes funciones miembro:

Función	Descripción
`matched_count()`	Devuelve la cantidad de documentos que coincidieron con el filtro de query, independientemente de cuántos se reemplazaron.
`modified_count()`	Devuelve el número de documentos modificados por la operación de reemplazo. Si un document sustituido es idéntico al original, no se incluye en este recuento.
`result()`	Devuelve el resultado de guardado masivo de la operación.
`upserted_id()`	Devuelve el ID del document que fue inserción en la base de datos, si el driver realizó una inserción.

Ejemplo: matched_count()

El siguiente ejemplo utiliza el método replace_one() para reemplazar un documento que tiene un valor de campo name de "Shake Shack" por uno nuevo que tiene un valor de campo name de "In-N-Out Burger". Luego llama a la función nodo matched_count() para imprimir el número de documentos que coinciden con el filtro de query:

auto query_filter = make_document(kvp("name", "Shake Shack"));
auto replace_doc = make_document(kvp("name", "In-N-Out Burger"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view());
std::cout << "Matched documents: " << result->matched_count() << std::endl;

Matched documents: 11

Ejemplo: upserted_id()

El siguiente ejemplo utiliza el método replace_one() para reemplazar un documento que tiene un valor de campo name de "In-N-Out Burger". Debido a que la opción upsert está configurada en true, el driver de C++ inserta un nuevo documento cuando el filtro de query no coincide con ningún documento existente. Luego, el código llama a la función nodo upserted_id() para imprimir el valor del campo _id del documento upsertado:

mongocxx::options::replace opts{}; 
opts.upsert(true);
auto query_filter = make_document(kvp("name", "In-N-Out Burger"));
auto replace_doc = make_document(kvp("name", "Shake Shack"));
auto result = collection.replace_one(query_filter.view(), replace_doc.view(), opts);
auto id = result->upserted_id()->get_value();
        
std::cout << "Upserted ID: " << id.get_oid().value.to_string() << std::endl;

// Your ID value may differ
Upserted ID: 67128c5ecc1f8c15ea26fcf8

Información Adicional

Para obtener más información sobre cómo crear filtros de query, se puede consultar la Especificar una query.

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

Update

Borrar