Insira documentos

Visão geral

Neste guia, você pode aprender como usar o driver Kotlin para adicionar documentos a uma coleção MongoDB realizando operações de inserção.

Uma operação de inserção insere um ou mais documentos em uma coleção MongoDB . Você pode executar uma operação de inserção usando os seguintes métodos:

• insertOne() para inserir um único documento

• insertMany() para inserir um ou mais documentos

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

O campo _id

Em uma coleção MongoDB , cada documento deve conter um campo _id que tenha um valor único.

O MongoDB permite gerenciar este campo de duas maneiras:

• Você mesmo pode definir este campo para cada documento, garantindo que cada valor do campo _id seja único.

• Você pode permitir que o acionador gere automaticamente um valor de ObjectId único para cada documento _id. Se você não definir manualmente um valor _id para um documento, o driver preencherá o campo com uma ObjectId.

A menos que você possa garantir exclusividade, recomendamos deixar o driver gerar automaticamente os valores de _id .

Para saber mais sobre o campo _id, consulte o guia Índices únicos no manual do servidor MongoDB.

Para aprender mais sobre a estrutura e as regras de documento, consulte o guia Documentos no manual do servidor MongoDB.

Inserir um 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.

O exemplo a seguir cria e insere um documento usando o método insertOne():

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

Para adicionar vários documentos a uma coleção MongoDB , use o método insertMany() e passe uma lista de documentos que você deseja adicionar. O método insertMany() insere documentos na ordem especificada até ocorrer uma exceção, se houver.

Se for bem-sucedido, o método retornará uma instância InsertManyResult representando _id de cada novo documento.

O exemplo seguinte cria e adiciona dois documentos a um List e insere o List utilizando o método insertMany():

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

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

Valor de retorno

O método insertOne() retorna uma instância InsertOneResult e o método insertMany() retorna uma instância InsertManyResult .

Você pode utilizar os seguintes métodos para recuperar informações de uma instância do InsertOneResult :

Você pode utilizar os seguintes métodos para recuperar informações de uma instância do InsertOneResult :

Exemplos totalmente executáveis

As seções seguintes fornecem exemplos completamente executáveis que demonstram como inserir documentos utilizando os métodos insertOne() e insertMany().

import com.mongodb.MongoException
import com.mongodb.kotlin.client.coroutine.MongoClient
import kotlinx.coroutines.runBlocking
import org.bson.codecs.pojo.annotations.BsonId
import org.bson.types.ObjectId
data class Movie(@BsonId val id: ObjectId, val title: String, val genres: List<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 result = collection.insertOne(
            Movie(ObjectId(), "Ski Bloopers", listOf("Documentary", "Comedy"))
        )
        println("Success! Inserted document id: " + result.insertedId)
    } catch (e: MongoException) {
        System.err.println("Unable to insert due to an error: $e")
    }
    mongoClient.close()
}

Success! Inserted document id: BsonObjectId{value=...}

import com.mongodb.MongoException
import com.mongodb.kotlin.client.coroutine.MongoClient
import kotlinx.coroutines.runBlocking
data class Movie(val title: 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")
    val movieList = listOf(
        Movie("Short Circuit 3"),
        Movie("The Lego Frozen Movie")
    )
    try {
        val result = collection.insertMany(movieList)
        println("Success! Inserted document ids: " + result.insertedIds)
    } catch (e: MongoException) {
        System.err.println("Unable to insert due to an error: $e")
    }
    mongoClient.close()
}

Success! Inserted document ids: {0=BsonObjectId{value=...}, 1=BsonObjectId{value=...}}

Documentação da API

Para saber mais sobre qualquer um dos métodos ou tipos discutidos neste guia, consulte a seguinte documentação da API:

• insertOne()

• InsertOneResult

• insertMany()

• InsertManyResult