Reemplazar Documentos

Overview

En esta guía, aprenderá a usar el controlador C para ejecutar una operación de reemplazo en una colección de MongoDB. Una operación de reemplazo funciona de forma diferente a una operación de actualización. Una operación de actualización modifica solo los campos especificados en un documento de destino. Una operación de reemplazo elimina todos los campos del documento de destino y los reemplaza por otros nuevos.

Para reemplazar un documento, utilice el mongoc_collection_replace_one() función.

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

Operación de reemplazo

Puede reemplazar el documento con mongoc_collection_replace_one(). Esta función elimina todos los campos excepto _id del primer documento que coincida con los criterios de búsqueda. A continuación, inserta los campos y valores especificados en el documento.

Parámetros requeridos

La función mongoc_collection_replace_one() requiere los siguientes parámetros:

Colección: especifica la colección en la que se realizará la operación de reemplazo.
Documento de filtro de consulta: Especifica los documentos de la colección que se deben buscar. La función selecciona el primer documento coincidente que se reemplazará. Para obtener más información sobre los filtros de consulta, consulte la sección "Documentos de filtro de consulta" en el manual de MongoDB Server.
Documento de reemplazo: especifica los campos y valores que se insertarán en el nuevo documento.
Documento de opciones: especifica opciones para personalizar la operación, o NULL.
Ubicación de los resultados: especifica un puntero al 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.

Ejemplo

El siguiente ejemplo utiliza la función mongoc_collection_replace_one() para reemplazar los campos y valores de un documento en el que el valor del campo name es "Pizza Town" por un documento en el que el valor del campo name es "Mongo's Pizza":

bson_t *query = BCON_NEW("name", "Pizza Town");
bson_t *replace = BCON_NEW(
    "name", "Mongo's Pizza",
    "cuisine", "Pizza",
    "address", "{",
    "street", "123 Pizza St",
    "zipCode", "10003",
    "}",
    "borough", "Manhattan"
);
bson_error_t error;
if (!mongoc_collection_replace_one(collection, query, replace, NULL, NULL, &error)) {
    fprintf(stderr, "Replace operation failed: %s\n", error.message);
}
bson_destroy(query);
bson_destroy(replace);

Importante

Los valores de los campos _id son inmutables. Si el documento de reemplazo especifica un valor para el campo _id, este debe ser idéntico al valor _id del documento existente.

Modificar la operación de reemplazo

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

Opción	Descripción
`upsert`	Specifies whether the replace operation performs an upsert operation if no documents match the query filter. For more information, see the upsert statement in the MongoDB Server manual. Defaults to `false`.
`bypassDocumentValidation`	Specifies whether the replace operation bypasses document validation. This lets you replace 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`.
`collation`	Specifies the kind of language collation to use when comparing text. For more information, see Collation in the MongoDB Server manual.
`hint`	Gets or sets the index to scan for documents. For more information, see the hint statement in the MongoDB Server manual.
`comment`	Attaches a comment to the operation. For more information, see the insert command fields guide in the MongoDB Server manual.

Ejemplo de opciones de reemplazo

El siguiente código usa la función mongoc_collection_replace_one() para encontrar el primer documento cuyo campo name tenga el valor "Food Town" y, a continuación, lo reemplaza por uno nuevo cuyo valor name sea "Food World". Dado que la opción upsert está establecida en true, el controlador inserta un nuevo documento si el filtro de consulta no coincide con ningún documento existente:

bson_t *query = BCON_NEW("name", "Food Town");
bson_t *replace = BCON_NEW(
    "name", "Food World",
    "cuisine", "Mixed",
    "address", "{",
    "street", "123 Food St",
    "zipCode", "10003",
    "}",
    "borough", "Manhattan"
);
bson_error_t error;
bson_t opts;
bson_init(&opts);
bson_append_bool(&opts, "upsert", -1, true);
if (!mongoc_collection_replace_one(collection, query, replace, &opts, NULL, &error)) {
    fprintf(stderr, "Replace operation failed: %s\n", error.message);
} 
bson_destroy(query);
bson_destroy(replace);
bson_destroy(&opts);

Información Adicional

Para obtener más información sobre las operaciones de actualización, consulte la Guía deactualización de documentos.

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 obtener más información sobre la mongoc_collection_replace_one() función, consulte la documentación de la API.

Volver

Acceder a datos desde un cursor

Update