/ /

Escritura de datos

Docs Home

Librerías de clientes

C++

Escritura de datos

Docs Home

Librerías de clientes

C++

Escritura de datos

Reemplazar Documentos

Overview

En esta guía, aprenderá a usar el controlador de C++ para ejecutar una operación de reemplazo en una colección de MongoDB. Una operación de reemplazo elimina todos los campos excepto el... _id campo en el documento de destino y los reemplaza por otros nuevos. Puede 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 la Conjuntos de datos de muestra de Atlas. Para acceder a esta colección desde su aplicación C++, cree una mongocxx::client instancia de que se conecte a un clúster de Atlas y asigne los siguientes valores a las variables db collection y:

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 muestra, consulte la guía de introducción a MongoDB.

Operación de reemplazo

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 coincida con los criterios de búsqueda. A continuación, inserta en el documento los campos y valores especificados.

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

Documento de filtro de consulta: Especifica el documento que se reemplazará. Para obtener más información sobre los filtros de consulta, consulte "Documentos de filtro de consulta" en el manual de MongoDB Server.
Reemplazar documento: especifica los campos y valores que se insertarán en el nuevo documento.

Importante

Los valores de los campos _id son inmutables. Si el 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(), consulte Busque un documento en la guía Recuperar datos.

opciones

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

Campo	Descripción
`bypass_document_validation`	Specifies whether the replace operation bypasses document validation. When set to `true`, this lets you replace a document with a new document that doesn't meet the schema validation requirements. For more information, see Schema Validation in the MongoDB Server manual. Defaults to `false`.
`collation`	Specifies the kind of language collation to use when sorting results. For more information, see Collation in the MongoDB Server manual.
`comment`	Specifies a comment of any valid BSON type to attach to the operation. Once set, this comment appears alongside records of this command in the following locations: mensajes de registro de mongod, en el `attr.command.cursor.comment` campo Salida del generador de perfiles de base de datos, en el `system.profile.command` `comment` campo `currentOp` salida, en el `currentOp.command` `comment` campo For more information, see the insert Command Fields guide in the MongoDB Server manual.
`hint`	Specifies the index to scan for documents that match the query filter. For more information, see the hint field in the MongoDB Server manual.
`let`	Specifies a document containing variables and their values to be used in the `replace_one()` method. This allows you to improve code readability by separating the variables from the operation text. Values must be constant or closed expressions that don't reference document fields. For more information, see the let field in the MongoDB Server manual.
`upsert`	Specifies whether the replace operation performs an upsert operation if no documents match the query filter. Defaults to `false`.
`write_concern`	Sets the write concern for the operation. For more information, see Write Concern in the MongoDB Server manual.

Ejemplo: Opción de pista

El siguiente ejemplo utiliza el método create_index() para crear un índice ascendente de un solo campo en el campo name. A continuación, pasa un objeto mongocxx::options::replace al método replace_one() tras asignar el nuevo índice a su campo hint. Esto indica a la operación de reemplazo que busque en el índice del campo name al reemplazar un documento cuyo valor de campo name es "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 obtener más información sobre los índices, consulte la guía Optimizar consultas con índices.

Ejemplo: Opción upsert

El siguiente ejemplo pasa un objeto mongocxx::options::replace al método replace_one() tras establecer el valor de su campo upsert en true. Dado que ningún documento coincide con el filtro de consulta, esto indica a la operación de reemplazo que inserte un nuevo documento con el valor de campo name en "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() devuelve una instancia de la clase mongocxx::result::replace. Esta clase contiene las siguientes funciones miembro:

Función	Descripción
`matched_count()`	Returns the number of documents that matched the query filter, regardless of how many were replaced.
`modified_count()`	Returns number of documents modified by the replace operation. If a replaced document is identical to the original, it is not included in this count.
`result()`	Returns the bulk write result for the operation.
`upserted_id()`	Returns the ID of the document that was upserted in the database, if the driver performed an upsert.

Ejemplo: matched_count()

El siguiente ejemplo utiliza el método replace_one() para reemplazar un documento cuyo valor de campo name es "Shake Shack" por un nuevo documento cuyo valor de campo name es "In-N-Out Burger". A continuación, llama a la función miembro matched_count() para imprimir el número de documentos que coinciden con el filtro de consulta:

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 consulta, consulte la guía Especificar una consulta.

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