Menu Docs
Página inicial do Docs
/
Idiomas
/
Kotlin
/
Driver de Kotlin Sync
/
Gravar dados

Insira documentos

Nesta página

Visão geral

Neste guia, você pode aprender como usar o driver Kotlin Sync 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 utilizando os métodos insertOne() e insertMany() .

Dados de amostra

Os exemplos neste guia usam a collection sample_restaurants.restaurants dos conjuntos de dados de amostra do Atlas. Para saber como criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de amostra, consulte o guia Iniciar com Atlas .

Os documentos nesta coleção são modelados pela seguinte classe de dados Kotlin :

data class Restaurant(val name: String, val borough: 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 .

Observação

Erros de _id duplicados

A definição de valores _id duplicados em uma coleção viola as restrições de índice único , o que faz com que o driver retorne um WriteError do método insertOne() ou um BulkWriteError do método insertMany() .

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

Para saber mais sobre a estrutura e as regras de documentos, consulte o guia Documentos no manual do MongoDB Server .

Inserir um documento

Para adicionar um único documento a uma coleção MongoDB, chame o método insertOne() e passe o documento que você deseja adicionar.

O exemplo a seguir insere um documento na coleção restaurants :

val doc = Restaurant("Sea Shell Bar", "Queens")
val result = collection.insertOne(doc)

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 exemplo a seguir insere uma lista de documentos na coleção restaurants :

val docs = listOf(
    Restaurant("Full Moon Grill", "Queens"),
    Restaurant("King's Cup", "Manhattan"),
)
val result = collection.insertMany(docs)

Modificar comportamento de inserção

O método insertOne() aceita opcionalmente um parâmetro InsertOneOptions que define opções para configurar a operação de inserção. Se você não especificar nenhuma opção, o driver executará a operação de inserção com as configurações padrão. Passe as opções como o último parâmetro para o método insertOne() .

A tabela a seguir descreve os métodos de configuração que você pode usar para configurar uma instância InsertOneOptions :

Método
Descrição

bypassDocumentValidation()

If set to true, allows the driver to ignore document-level validation.
Defaults to false.

comment()

Sets a comment to attach to the operation. For more information, see the insert command fields guide in the MongoDB Server manual for more information.

Você pode definir as configurações anteriores no método insertMany() configurando uma instância InsertManyOptions . Você também pode usar o método ordered() para especificar a ordem em que o driver insere documentos no MongoDB:

Método
Descrição

ordered()

If set to true, the driver sends documents to the server in the order provided. If an error occurs, the driver cancels all remaining insert operations.
Defaults to true.

Passe as opções como o último parâmetro para o método insertMany() .

Exemplo de modificação de inserção

O código a seguir usa o método bypassDocumentValidation() para definir a opção de ignorar as regras de validação do documento . Em seguida, o exemplo utiliza o método insertMany() para adicionar novos documentos à coleção restaurants .

val opts = InsertManyOptions().bypassDocumentValidation(true)
val docs = listOf(
    Restaurant("Full Moon Grill", "Queens"),
    Restaurant("King's Cup", "Manhattan"),
)
val result = collection.insertMany(docs, opts)

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 :

Método
Descrição

getInsertedId()

Indica o valor _id do documento inserido.

wasAcknowledged()

Retorna true se o servidor reconhecer o resultado.

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

Método
Descrição

getInsertedIds()

Indica os valores _id dos documentos inseridos.

wasAcknowledged()

Retorna true se o servidor reconhecer o resultado.

Observação

Se o método wasAcknowledged() retornar false, tentar acessar os valores _id resultará em uma exceção InvalidOperation . O driver não pode determinar esses valores se o servidor não reconhecer a operação de gravação.

Informações adicionais

Para obter exemplos de código executáveis que demonstram como inserir documentos usando o driver Kotlin Sync, consulte Gravar dados no MongoDB.

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:

Voltar

Gravar dados

Próximo

Update