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, use el mongoc_collection_replace_one() función.

Datos de muestra

Los ejemplos de esta guía usan la colección restaurants 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.

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 necesarios

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

Colección: Especifica la colección en la que se debe realizar la operación de reemplazo.
Documento de filtro de query: Especifica con qué documentos de colección hacer coincidir. La función selecciona el primer documento coincidente para reemplazar. Para obtener más información sobre los filtros de query, consulta la sección Documentos de filtros de query en el manual de MongoDB Server.
Documento de reemplazo: Especifica los campos y valores que se deben insertar 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 tu 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 utiliza la función mongoc_collection_replace_one() para encontrar el primer documento en el que el campo name tiene el valor "Food Town", y luego sustituye este documento por uno nuevo en el que el valor name es "Food World". Dado que la opción upsert está configurada en true, el controlador inserta un nuevo documento si el filtro de query 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, consulta el Actualizar Documentos guía.

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 función mongoc_collection_replace_one(), consulta la documentación de la API.

Volver

Acceder a datos desde un cursor

Update