Substituir documentos

Visão geral

Neste guia, você pode aprender como usar o driver Kotlin para substituir documentos em uma coleção MongoDB . Uma operação de substituição usa um filtro de query para corresponder a um documento em uma coleção e, em seguida, substitui o documento por um novo.

Substituir um documento

O métodoreplaceOne() remove todos os campos e valores existentes no documento correspondente (exceto o _id campo ) e insere os campos e valores do documento de substituição.

Você pode chamar o método replaceOne() em uma instância MongoCollection da seguinte forma:

collection.replaceOne(<query>, <replacementDocument>)

Se vários documentos corresponderem ao filtro de query especificado no método replaceOne(), a operação substituirá o primeiro resultado. Você pode especificar uma classificação em uma instância do ReplaceOptions para aplicar um pedido aos documentos correspondentes antes que o driver execute a operação de substituição, conforme mostrado no código a seguir:

val opts = ReplaceOptions().sort(Sorts.ascending(PaintOrder::color.name))

Se zero documentos corresponderem ao filtro de query na operação de substituição, replaceOne() não fará alterações nos documentos na coleção.Consulte o guia Upsert para saber como inserir um novo documento em vez de substituir um se nenhum documento corresponder.

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

E11000 duplicate key error collection: ...

Substituir um exemplo

Uma loja de tintas vende cinco cores diferentes de tinta. Os documentos na seguinte coleção representam cores de tinta no inventário da loja:

{ "_id": 1, "color": "red", "qty": 5 }
{ "_id": 2, "color": "purple", "qty": 8 }
{ "_id": 3, "color": "yellow", "qty": 0 }
{ "_id": 4, "color": "green", "qty": 6 }
{ "_id": 5, "color": "pink", "qty": 20 }

A seguinte classe de dados Kotlin modela esses dados:

data class PaintOrder(
    @BsonId val id: Int,
    val color: String,
    val qty: Int
)

A loja de tintas deve atualizar seu inventário para substituir 20 latas de tinta cor de laranja por 25 latas de tinta laranja.

Para atualizar o inventário, chame o método replaceOne():

val filter = Filters.eq(PaintOrder::color.name, "pink")
val update = PaintOrder(5, "orange", 25)
val result = collection.replaceOne(filter, update)
println("Matched document count: $result.matchedCount")
println("Modified document count: $result.modifiedCount")

  Matched document count: 1
  Modified document count: 1

A operação de substituição anterior cria o seguinte documento:

 { "_id": 5, "color": "orange", "qty": 25 }

Exemplo de substituição avançada um

No exemplo a seguir, o replaceOne() método substitui a primeira correspondência do filtro de query na movies coleção do conjunto de dados Atlas por um documento de substituição. A operação exclui todos os campos, exceto,_id do documento original e insere os campos do documento de substituição. A seguinte Movie classe de dados modela os documentos nesta coleção para uso com o driver Kotlin :

data class Movie(
    val title: String,
    val year: Int,
    val genres: List<String>,
    val rated: String,
    val plot: String,
    val runtime: Int,
    val imdb: IMDB,
    val fullplot: String? = "No full plot",
){
    data class IMDB(
        val rating: Double
    )
}

Antes da operação replaceOne() ser executada, o documento original contém vários campos que descrevem o filme. Após a operação ser executada, o documento resultante conterá somente os campos especificados pelo documento de substituição (title e fullplot) e o campo _id .

O exemplo a seguir utiliza os seguintes objetos e métodos:

• Um filtro de queries que é passado para o método replaceOne(). O filtro eq corresponde apenas a filmes com o título que corresponde exatamente ao texto "Music of the Heart".

• Um documento de substituição que contém o documento que substitui o documento correspondente , se ele existir.

• Um objeto ReplaceOptions com a upsert opção definida true como. Esta opção especifica que o método insere os dados contidos no documento de substituição se o filtro de query não corresponder a nenhum documento.

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()
}

O exemplo anterior retorna a seguinte saída:

Modified document count: 1
Upserted id: null

Se o exemplo anterior resultou em um upsert, o código retornará a seguinte saída:

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

Se você fizer query do documento substituído, a query retornará a seguinte saída:

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

Informações adicionais

Para saber mais sobre os métodos e classes utilizados nesta página, consulte a seguinte documentação da API:

• replaceOne

• ReplaceOptions

• UpdateResult

• eq()