Reemplazar un documento

Puede reemplazar un solo documento utilizando el replaceOne() Método en un objeto MongoCollection. Este método elimina todos los campos y valores existentes de un documento (excepto el campo _id) y lo sustituye por el documento de reemplazo.

El método replaceOne() acepta un filtro de consulta que coincide con el documento que desea reemplazar y un documento de reemplazo que contiene los datos que desea guardar en lugar del documento coincidente. El método replaceOne() solo reemplaza el primer documento que coincide con el filtro.

Opcionalmente, puede pasar una instancia de ReplaceOptions al método replaceOne() para especificar su comportamiento. Por ejemplo, si establece el campo upsert del objeto ReplaceOptions como true, la operación insertará un nuevo documento a partir de los campos del documento de reemplazo si ningún documento coincide con el filtro de consulta. Consulte el enlace a la documentación de la API ReplaceOptions al final de esta página para obtener más información.

Tras una ejecución correcta, el método replaceOne() devuelve una instancia de UpdateResult. Puede recuperar información como el número de documentos modificados llamando al método getModifiedCount(). También puede recuperar el valor del campo _id del documento llamando al método getUpsertedId() si estableció upsert(true) en la instancia ReplaceOptions y la operación resultó en la inserción de un nuevo documento.

Si la operación de reemplazo falla, el controlador genera una excepción. Por ejemplo, si intenta especificar un valor para el campo inmutable _id en el documento de reemplazo que difiere del documento original, el método genera una excepción MongoWriteException con el mensaje:

After applying the update, the (immutable) field '_id' was found to have been altered to _id: ObjectId('...)

Si el documento de reemplazo contiene un cambio que viola las reglas de índice único, el método arroja un MongoWriteException con un mensaje de error que debería verse así:

E11000 duplicate key error collection: ...

Para obtener más información sobre los tipos de excepciones generadas en condiciones específicas, consulte la documentación de la API para replaceOne(), cuyo enlace se encuentra en la parte inferior de esta página.

import com.mongodb.MongoException
import com.mongodb.client.model.Filters
import com.mongodb.client.model.ReplaceOptions
import com.mongodb.kotlin.client.coroutine.MongoClient
import kotlinx.coroutines.runBlocking
data class Movie(val title: String, val fullplot: String)
fun main() = runBlocking {
    // Replace the uri string with your MongoDB deployment's connection string
    val uri = "<connection string uri>"
    val mongoClient = MongoClient.create(uri)
    val database = mongoClient.getDatabase("sample_mflix")
    val collection = database.getCollection<Movie>("movies")
    try {
        val query = Filters.eq("title", "Music of the Heart")
        val replaceDocument = Movie( "50 Violins", " A dramatization of the true story of Roberta Guaspari who co-founded the Opus 118 Harlem School of Music")
        val options = ReplaceOptions().upsert(true)
        val result = collection.replaceOne(query, replaceDocument, options)
        println("Modified document count: " + result.modifiedCount)
        println("Upserted id: " + result.upsertedId) // only contains a non-null value when an upsert is performed
    } catch (e: MongoException) {
        System.err.println("Unable to replace due to an error: $e")
    }
    mongoClient.close()
}

Modified document count: 1
Upserted id: null

Modified document count: 0
Upserted id: BsonObjectId{value=...}

Movie(title=50 Violins, fullplot= A dramatization of the true story of Roberta Guaspari who co-founded the Opus 118 Harlem School of Music)