Reemplazar Documentos

Overview

En esta guía, puedes aprender cómo utilizar el driver de C para ejecutar una operación de reemplazo en una colección de MongoDB. Una operación de reemplazo se realiza de forma diferente a una operación de actualización. Una operación de actualización modifica únicamente los campos especificados en un documento de destino. Una operación de sustitución remueve todos los campos en el documento de destino y los reemplaza por otros nuevos.

Para reemplazar un documento, utiliza la función mongoc_collection_replace_one().

Datos de muestra

Los ejemplos en 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 aprender a crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de muestra, consulta la guía MongoDB Primeros Pasos.

Operación de reemplazo

Puedes realizar una operación de reemplazo utilizando mongoc_collection_replace_one(). Esta función elimina todos los campos, excepto el campo _id del primer documento que cumpla con los criterios de búsqueda. Luego, inserta los campos y valores que especifiques 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 que se puede sobrescribir y 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`	Especifica si la operación de reemplazo realiza una operación inserción si ningún documentos coincide con el filtro de query. Para obtener más información, consulta la instrucción de inserción en el manual de MongoDB Server. por defecto en `false`.
`bypassDocumentValidation`	Especifica si la operación de reemplazo omite la validación del documento. Esto le permite reemplazar documentos que no cumplen los requisitos de validación de esquema, si los hay. Para obtener más información sobre la validación de esquemas, consulte Validación de esquemas en el manual de MongoDB Server. Por defecto, se establece en `false`.
`collation`	Especifica el tipo de intercalación de lenguaje que se debe usar al comparar texto. Para obtener más información, consulte Intercalación en el manual de MongoDB Server.
`hint`	Obtiene o define el índice para escanear documentos. Para obtener más información, consulta la instrucción de sugerencia en el manual del MongoDB Server.
`comment`	Adjunta un comentario a la operación. Para obtener más información, consulte la guía insertar campos de comando en el manual de MongoDB Server.

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, consulte la guía Actualizar documentos.

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 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