/ /

Reemplazar Documentos

Overview

En esta guía, puedes aprender cómo utilizar el controlador Scala para realizar una operación de reemplazo en un documento en una colección de MongoDB. Una operación de reemplazo remueve todos los campos y valores de un documento específico, excepto el campo _id, y agrega nuevos campos y valores que usted especifica. Esta operación difiere de una operación de actualización, que solo cambia 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 utilizan la colección restaurants en la base de datos sample_restaurants de los conjuntos de datos de ejemplo de Atlas. Para acceder a esta colección desde su aplicación Scala, cree un objeto MongoClient que se conecte a un clúster de Atlas y asigne los siguientes valores a sus variables database y collection:

val database: MongoDatabase = mongoClient.getDatabase("sample_restaurants")
val collection: MongoCollection[Document] = database.getCollection("restaurants")

Para aprender cómo crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de ejemplo, consulta la guía MongoDB Get Started.

Operación de reemplazo

Puedes realizar una operación de reemplazo en MongoDB usando el método replaceOne(). Este método remueve todos los campos excepto el campo _id del primer documento que coincida con el filtro de query especificado. Luego agrega los campos y valores que especifiques 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 = equal("name", "Primola Restaurant")
val replacement = Document(
  "name" -> "Frutti Di Mare",
  "borough" -> "Queens",
  "cuisine" -> "Seafood",
  "owner" -> "Sal Thomas"
)
val observable: Observable[UpdateResult] = collection.replaceOne(filter, replacement)
observable.subscribe(new Observer[UpdateResult] {
  override def onNext(result: UpdateResult): Unit = println(s"Replaced document count: ${result.getModifiedCount}")
  override def onError(e: Throwable): Unit = println(s"Failed: ${e.getMessage}")
  override def onComplete(): Unit = println("Completed")
})

Replaced document count: 1
Completed

Importante

El valor del campo _id es inmutable. Si su documento de reemplazo contiene un valor para el campo _id, este debe ser el mismo que el valor _id del documento existente o el controlador lanzará un WriteError.

Personalizar la operación de reemplazo

El método replaceOne() acepta opcionalmente un parámetro con el tipo de dato ReplaceOptions. La clase ReplaceOptions contiene métodos setters que se pueden utilizar para configurar la opció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 en la clase ReplaceOptions:

Método	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 `false` es.
`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 options = ReplaceOptions().upsert(true)
val observable: Observable[UpdateResult] = collection.replaceOne(filter, replacement, options)
observable.subscribe(new Observer[UpdateResult] {
  override def onNext(result: UpdateResult): Unit = println(s"Replaced document count: ${result.getModifiedCount}")
  override def onError(e: Throwable): Unit = println(s"Failed: ${e.getMessage}")
  override def onComplete(): Unit = println("Completed")
})

Replaced document count: 1
Completed

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:

Método	Descripción
`getMatchedCount()`	Devuelve el número de documentos que coinciden con el filtro de la consulta.
`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 documento que el controlador insertó o actualizó en la base de datos, si lo hay.

Información Adicional

Para ver un ejemplo de código ejecutable que demuestre cómo reemplazar un documento, consulte Guardar datos en MongoDB.

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

Insert

Update