/ /

Update Documents

Overview

En esta guía, puedes aprender a usar el controlador Sync de Kotlin para actualizar documentos en una colección de MongoDB utilizando los métodos updateOne() y updateMany().

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 address: Document
)

Operaciones de actualizar

Puedes 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 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.
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 en los que el valor name es "Starbucks". La actualización renombra el campo address a location.

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

Personaliza la operación de actualizar

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

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

Propiedad	Descripción
`upsert()`	Especifica si la operación de actualización 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 la instrucción `upsert` 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 documents coinciden con el filtro de query que se pasa al método `updateOne()`, la operación actualiza el primer resultado. Puede establecer esta opción para aplicar un orden a los documents coincidentes y tener más control sobre qué document se actualiza.
`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.
`arrayFilters()`	Proporciona una lista de filtros que indicas para seleccionar a qué elementos del arreglo se aplica la actualización.
`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 document. Para más información, consulta la instrucción let en la documentación del MongoDB Server.
`comment()`	Establece un comentario para adjuntar a la operación. Para obtener más información, consulta la guía de campos de comando de actualización en el manual del servidor de MongoDB para obtener más información.

Ejemplo de inserción o actualización de documentos

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

Dado que la opción upsert está configurada en true, el driver inserta un nuevo documento que tiene los campos y valores especificados en el documento de actualización si el filtro de query 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 utilizar los siguientes métodos para acceder a la información desde 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.

Nota

Si el método wasAcknowledged() retorna false, intentar acceder a otra información desde la instancia UpdateResult resulta en una excepción InvalidOperation. El driver no puede determinar estos valores si el servidor no reconoce la operación de guardado.

Información Adicional

Para ver ejemplos de código ejecutables que demuestran cómo actualizar documentos utilizando el driver Kotlin sincronizar, 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

Acceder a datos desde un cursor

Reemplazar Documentos