Menu Docs
Página inicial do Docs
/
Idiomas
/
Kotlin
/
Kotlin Coroutine

Inserir operações

Nesta página

  • Visão geral
  • Uma observação sobre _id
  • Inserir um único documento
  • Insira vários documentos
  • Resumo

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.

Observação

Os valores _id duplicados violam restrições de índice único, resultando em um WriteError.

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.

Exemplo

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

Para obter mais informações sobre os métodos e classes descritas nesta seção, consulte os seguintes recursos:

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.

Dica

Use um blocotry-catch para obter uma confirmação para documentos processados com êxito antes que o erro ocorra. O resultado consiste em documentos que o MongoDB pode processar:

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]

Se você examinar sua coleção, deverá ver os seguintes documentos:

{ "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.

Exemplo

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 a document with the following ids: ${result.insertedIds.toList()}")
Inserted documents with the following ids: [60930c3aa982931c20ef6cd7, 60930c3aa982931c20ef6cd8]

Para obter mais informações sobre os métodos e classes descritas nesta seção, consulte os seguintes recursos:

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.

Próximo

MongoDB Kotlin driver