/ /

Update Documents

Overview

En esta guía, puede aprender a usar el controlador de sincronización de Kotlin para actualizar documentos en una colección de MongoDB mediante el uso de updateOne() y updateMany() métodos.

Datos de muestra

Los ejemplos de esta guía utilizan la colección sample_restaurants.restaurants de Conjuntos de datos de muestra de Atlas. Para aprender a crear una implementación gratuita de MongoDB y cargar los conjuntos de datos de muestra, consulte la guía de introducción a MongoDB.

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

data class Restaurant(
    val name: String,
    val borough: String,
    val cuisine: String,
    val address: Document
)

Operaciones de actualizar

Puede actualizar documentos en MongoDB utilizando los siguientes métodos:

updateOne(), que actualiza el primer documento que coincide con los criterios de búsqueda
updateMany(), que actualiza todos los documentos que coinciden con los criterios de búsqueda

Cada método de actualización requiere los siguientes parámetros:

Filtro de consulta, que identifica los documentos que se deben actualizar. Para obtener más información sobre los filtros de consulta, consulte Especifique una guía de consulta.
Actualizar documento, el cual especifica el operador de actualización o el tipo de actualización a realizar, así como los campos y valores a actualizar. Para obtener una lista de los operadores de actualización y sus usos, consulta la página de la guía de Operadores de actualización de campos en el manual de MongoDB Server.

Actualizar un documento

El siguiente ejemplo utiliza el método updateOne() para actualizar el valor name de un documento de "Happy Garden" a "Mountain House":

val filter = eq(Restaurant::name.name, "Happy Garden")
val update = set(Restaurant::name.name, "Mountain House")
val result = collection.updateOne(filter, update)

Actualizar muchos documentos

El siguiente ejemplo utiliza el método updateMany() para actualizar todos los documentos cuyo valor name es "Starbucks". La actualización cambia el nombre del campo address a location.

val filter = eq(Restaurant::name.name, "Starbucks")
val update = rename(Restaurant::address.name, "location")
val result = collection.updateMany(filter, update)

Personalizar la operación de actualización

Los métodos updateOne() y updateMany() aceptan opcionalmente un parámetro que establece opciones para configurar la operación de actualización. Si no se especifica ninguna opción, el controlador realiza las operaciones de actualización con la configuración predeterminada.

La siguiente tabla describe los métodos de configuración que puede utilizar para configurar una instancia UpdateOptions:

Propiedad	Descripción
`upsert()`	Specifies whether the update 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`
`sort(Bson sort)`	Sets the sort criteria to apply to the operation. If multiple documents match the query filter that you pass to the `updateOne()` method, the operation updates the first result. You can set this option to apply an order to matched documents to have more control over which document is updated.
`bypassDocumentValidation()`	Specifies whether the update operation bypasses document validation. This lets you update 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 sorting results. For more information, see Collation in the MongoDB Server manual.
`arrayFilters()`	Provides a list of filters that you specify to select which array elements the update applies to.
`hint()`	Sets the index to use when matching documents. For more information, see the hint statement in the MongoDB Server manual.
`let()`	Provides a map of parameter names and values to set top-level variables for the operation. Values must be constant or closed expressions that don't reference document fields. For more information, see the let statement in the MongoDB Server manual.
`comment()`	Sets a comment to attach to the operation. For more information, see the update command fields guide in the MongoDB Server manual for more information.

Ejemplo de inserción de documentos

El siguiente código utiliza el método updateOne() para buscar coincidencias en documentos cuyo valor del campo name sea "Sunrise Pizzeria". A continuación, establece el valor borough en el primer documento coincidente como "Queens" y el valor cuisine como "Italian".

Debido a que la opción upsert está establecida en true, el controlador inserta un nuevo documento que tiene los campos y valores especificados en el documento de actualización si el filtro de consulta no coincide con ningún documento existente.

val opts = UpdateOptions().upsert(true)
val filter = eq(Restaurant::name.name, "Sunrise Pizzeria")
val update = combine(
    set(Restaurant::borough.name, "Queens"),
    set(Restaurant::cuisine.name, "Italian")
)
collection.updateOne(filter, update, opts)

Valor de retorno

Los métodos updateOne() y updateMany() devuelven cada uno un objeto UpdateResult. Puede usar los siguientes métodos para acceder a la información de una instancia UpdateResult:

Propiedad	Descripción
`getMatchedCount()`	Returns the number of documents that matched the query filter, regardless of how many updates were performed.
`getModifiedCount()`	Returns the number of documents modified by the update operation. If an updated document is identical to the original, it is not included in this count.
`wasAcknowledged()`	Returns `true` if the server acknowledged the result.
`getUpsertedId()`	Returns the `_id` value of the document that was upserted in the database, if the driver performed an upsert.

Nota

Si el método wasAcknowledged() devuelve false, al intentar acceder a otra información de la instancia UpdateResult se genera una excepción InvalidOperation. El controlador no puede determinar estos valores si el servidor no confirma la operación de escritura.

Información Adicional

Para ver ejemplos de código ejecutables que demuestran cómo actualizar documentos mediante el controlador Kotlin Sync, consulte 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

Acceder a datos desde un cursor

Reemplazar Documentos