/ /

Reemplazar Documentos

Overview

En esta guía, puedes aprender cómo utilizar el driver sincronizar de Kotlin para realizar una operación de reemplazo en un documento de una colección MongoDB. Una operación de reemplazo elimina todos los campos y valores de un documento especificado excepto el campo _id, y añade nuevos campos y valores que se especifiquen. Esta operación difiere de una operación de actualización, que cambia solo los campos especificados en uno o más documentos.

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

Datos de muestra

Los ejemplos de esta guía usan la colección sample_restaurants.restaurants de los conjuntos de datos de muestra de Atlas. Para aprender cómo crear una implementación gratuita de MongoDB y cargar los conjuntos de datos de muestra, consulta la guía MongoDB Comenzar.

Los documentos de esta colección están modelados por la siguiente clase de datos Kotlin:

data class Restaurant(
    val name: String,
    val borough: String,
    val cuisine: String,
    val owner: String?,
)

Operación de reemplazo

Puedes realizar una operación de reemplazo en MongoDB utilizando el método replaceOne(). Este método elimina todos los campos excepto el campo _id del primer documento que coincida con el filtro de query. Luego añade los campos y valores que usted especifica al documento vacío.

Parámetros necesarios

Debes pasar los siguientes parámetros al método replaceOne():

Filtro de query, que se utiliza para determinar qué documentos se actualizarán. Para obtener más información sobre los filtros de query, consulta la guía Especificar una query.
Documento de reemplazo, que especifica los campos y valores que deseas reemplazar con los campos y valores existentes.

Reemplazar un documento

El siguiente ejemplo utiliza el método replaceOne() para reemplazar los campos y valores de un documento en el que el valor del campo name es "Primola Restaurant":

val filter = Filters.eq(Restaurant::name.name, "Primola Restaurant")
val replacement = Restaurant(
    "Frutti Di Mare",
    "Queens",
    "Seafood",
    owner = "Sal Thomas"
)
val result = collection.replaceOne(filter, replacement)

Importante

Los valores de los campos _id son inmutables. Si su documento de reemplazo especifica un valor para el campo _id, debe ser igual que el valor de _id del documento existente o el controlador generará un WriteError.

Personalizar la operación de reemplazo

El método replaceOne() acepta opcionalmente un parámetro que configura opciones para configurar la operación de reemplazo. Si no especifica ninguna opción, el driver realiza la operación de reemplazo con la configuración por defecto.

La siguiente tabla describe los métodos setter que puedes usar para configurar una instancia de ReplaceOptions:

Propiedad	Descripción
`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. Para obtener más información, consulte el comportamiento de la inserción/actualización en el manual del servidor MongoDB. El valor predeterminado es.`false`
`sort(Bson sort)`	Establece los criterios de ordenación que se aplicarán a la operación. Si varios documentos coinciden con el filtro de consulta que se pasa al método `replaceOne()`, la operación reemplaza el primer resultado. Puede configurar esta opción para aplicar un orden a los documentos coincidentes y así tener mayor control sobre qué documento se reemplaza.
`bypassDocumentValidation()`	Especifica si la operación de actualización omite la validación del documento. Esto permite actualizar documentos que no cumplen con los requisitos de validación del esquema, si los hubiera. Para obtener más información sobre la validación del esquema, 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.
`hint()`	Establece el índice que se utilizará al emparejar document. Para más información, consulta la instrucción de pistas en el manual de MongoDB Server.
`let()`	Proporciona un mapa de nombres y valores de parámetros para establecer variables de nivel superior para la operación. Los valores deben ser constantes o expresiones cerradas que no hagan referencia a campos del documento.
`comment()`	Establece un comentario para adjuntar a la operación.

El siguiente código establece la opción upsert en true, lo que indica al driver que inserte un nuevo documento con los campos y valores especificados en el documento de reemplazo si el filtro de query no coincide con ningún documento existente:

val opts = ReplaceOptions().upsert(true)
val result = collection.replaceOne(filter, replacement, opts)

Valor de retorno

El método replaceOne() retorna un objeto UpdateResult. Puedes usar los siguientes métodos para acceder a la información de una instancia de UpdateResult:

Propiedad	Descripción
`getMatchedCount()`	Devuelve el número de document que coincidieron con el filtro de query, independientemente de cuántas actualizaciones se hayan realizado.
`getModifiedCount()`	Devuelve el número de documentos modificados por la operación de actualización. Si un document actualizado es idéntico al original, no se incluye en este recuento.
`wasAcknowledged()`	Devuelve `true` si el servidor reconoce el resultado.
`getUpsertedId()`	Devuelve el valor `_id` del document que fue inserción en la base de datos, si el driver realizó una inserción.

Información Adicional

Para ver un ejemplo de código ejecutable que demuestre cómo reemplazar un documento, consulta Insertar documentos.

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 Documents

Delete Documents