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 _id
campo
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 umaObjectId
.
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 exclusivo, 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: