Inserir operações

Visão geral

Neste guia, você pode aprender como inserir documentos com o driver MongoDB Kotlin.

Você pode usar o MongoDB para recuperar, atualizar e excluir informações. Para uma dessas operações, tais informações, como perfis de usuário e pedidos, precisam existir no MongoDB. Para que elas existam, você precisa primeiro realizar uma operação de inserção.

Uma operação de inserção insere um ou vários documentos no MongoDB usando os métodos insertOne() , insertMany() e bulkWrite() .

As seções a seguir focam em insertOne() e insertMany(). Para obter informações sobre como usar o método bulkWrite() , consulte nosso guia sobre operações em massa.

Nos exemplos a seguir, uma loja de tintas tem um estoque de diferentes cores de tinta. Esses dados são modelados com a seguinte classe de dados Kotlin:

data class PaintOrder(
    @BsonId val id: ObjectId? = null,
    val qty: Int,
    val color: String
)

Uma observação sobre _id

Ao inserir um documento, o MongoDB impõe uma restrição aos seus documentos por padrão: cada documento deve conter um campo _id exclusivo.

Há duas maneiras de gerenciar este campo:

• Você mesmo pode gerenciar esse campo, garantindo que cada valor usado seja exclusivo.

• Você pode permitir que o acionador gere automaticamente valores de ObjectId únicos.

A menos que você tenha fornecido garantias sólidas de exclusividade, recomendamos que deixe o driver gerar automaticamente os valores de _id.

Para obter informações adicionais sobre índices únicos, consulte a entrada manual sobre Índices únicos.

Inserir um único documento

Use o método insertOne() quando quiser inserir um único documento.

Em uma inserção bem-sucedida, o método retorna uma instância do InsertOneResult representando o _id do novo documento.

val paintOrder = PaintOrder(ObjectId(), 5, "red")
val result = collection.insertOne(paintOrder)
val insertedId = result.insertedId?.asObjectId()?.value
println("Inserted a document with the following id: $insertedId")

Inserted a document with the following id: 60930c39a982931c20ef6cd6

Insira vários documentos

Use o método insertMany() quando quiser inserir vários documentos. Este método insere documentos na ordem especificada até ocorrer uma exceção, se houver.

Por exemplo, suponha que você queira inserir os seguintes documentos:

{ "color": "red", "qty": 5 }
{ "color": "purple", "qty": 10 }
{ "color": "yellow", "qty": 3 }
{ "color": "blue", "qty": 8 }

Se você tentar inserir esses documentos, um WriteError ocorrerá no terceiro documento, e os documentos anteriores ao erro serão inseridos na sua collection.

val result = collection.insertMany(paintOrders)
try {
    println("Inserted documents with the following ids: ${result.insertedIds}")
} catch(e: MongoBulkWriteException){
    val insertedIds = e.writeResult.inserts.map { it.id.asInt32().value }
    println(
        "A MongoBulkWriteException occurred, but there are " +
        "successfully processed documents with the following ids: $insertedIds"
    )
    collection.find().collect { println(it) }
}

A MongoBulkWriteException occurred, but there are successfully processed
documents with the following ids: [60930c3aa982931c20ef6cd7, 644ad1378ea29443837a14e9, 60930c3aa982931c20ef6cd8]

{ "color": "red", "qty": 5 }
{ "color": "purple", "qty": 10 }

Em uma inserção bem-sucedida, o método retorna uma instância do InsertManyResult representando o _id de cada novo documento.

val paintOrders = listOf(
    PaintOrder(ObjectId(), 5, "red"),
    PaintOrder(ObjectId(), 10, "purple")
)
val result = collection.insertMany(paintOrders)
println("Inserted a document with the following ids: ${result.insertedIds.toList()}")

Inserted documents with the following ids: [60930c3aa982931c20ef6cd7, 60930c3aa982931c20ef6cd8]

Resumo

Há três maneiras de realizar uma operação de inserção, mas nos concentramos em duas:

• O método insertOne() insere um único documento.

• O método insertMany() insere vários documentos.

Ambos os métodos geram automaticamente um _id se você omitir o campo em seu documento.

Se a inserção for bem-sucedida, ambos os métodos retornarão uma instância representando _id de cada novo documento.