Overview
En esta guía, puede aprender a utilizar el controlador Kotlin Sync para agregar documentos a una colección de MongoDB mediante la realización de operaciones de inserción.
Una operación de inserción inserta uno o más documentos en una colección de MongoDB. Puede realizar una operación de inserción utilizando la insertOne() y insertMany() métodos.
Datos de muestra
Los ejemplos en esta guía utilizan la colección sample_restaurants.restaurants de la conjuntos de datos de muestra de Atlas. Para aprender a crear una implementación gratuita de MongoDB y cargar los conjuntos de datos de ejemplo, consulta la guía de MongoDB Get Started.
Los documentos de esta colección están modelados por la siguiente clase de datos Kotlin:
data class Restaurant(val name: String, val borough: String)
El campo _id
En una colección de MongoDB, cada documento debe contener un campo _id que tenga un valor único.
MongoDB permite gestionar este campo de dos formas:
Uno mismo puede configurar este campo para cada documento, asegurando que el valor de cada campo
_idsea único.Se puede permitir que el controlador genere automáticamente un valor único de
ObjectIdpara cada documento_id. Si no se asigna manualmente un valor_ida un documento, el controlador rellena el campo con unObjectId.
A menos que pueda garantizar la exclusividad, recomendamos dejar que el controlador genere automáticamente los valores de _id.
Nota
Errores duplicados de _id
Establecer valores de _id duplicados en una colección infringe las restricciones de índices únicos, lo que provoca que el controlador devuelva un WriteError del método insertOne() o un BulkWriteError del método insertMany().
Para obtener más información sobre el campo _id, consulta la guía Índices únicos en el manual del MongoDB Server.
Para obtener más información sobre la estructura y las reglas de los documentos, consulta la guía de Documentos en el manual de MongoDB Server.
Inserta un documento
Para añadir un único documento a una colección de MongoDB, llama al método insertOne() y pasa el documento que quieras añadir.
El siguiente ejemplo inserta un documento en la colección restaurants:
val doc = Restaurant("Sea Shell Bar", "Queens") val result = collection.insertOne(doc)
Inserta varios documentos
Para agregar varios documentos a una colección de MongoDB, utilice el método insertMany() y pase una lista de los documentos que desea agregar.
El siguiente ejemplo inserta una lista de documentos en la colección restaurants:
val docs = listOf( Restaurant("Full Moon Grill", "Queens"), Restaurant("King's Cup", "Manhattan"), ) val result = collection.insertMany(docs)
Modificar el comportamiento de inserción
El método insertOne() acepta opcionalmente un parámetro InsertOneOptions que establece opciones para configurar la operación de inserción. Si no se especifican opciones, el controlador realiza la operación de inserción con la configuración por defecto. Pasa las opciones como el último parámetro al método insertOne().
La siguiente tabla describe los métodos setter que puedes usar para configurar una instancia de InsertOneOptions:
Método | Descripción |
|---|---|
| If set to true, allows the driver to ignore
document-level validation.Defaults to false. |
| 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. |
Puede establecer los ajustes anteriores en el método insertMany() configurando una instancia de InsertManyOptions. También puedes utilizar el método setter ordered() para especificar el orden en que el controlador inserta documentos en MongoDB:
Método | Descripción |
|---|---|
| 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. |
Transmita opciones como el último parámetro al método insertMany().
Modificar ejemplo de inserción
El siguiente código usa el método bypassDocumentValidation() para configurar la opción de ignorar las reglas de validación de documentos. Luego, el ejemplo utiliza el método insertMany() para añadir nuevos documentos a la colección 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
El método insertOne() devuelve una instancia de InsertOneResult, y el método insertMany() devuelve una instancia de InsertManyResult.
Puede usar los siguientes métodos para recuperar información de una instancia de InsertOneResult:
Método | Descripción |
|---|---|
| Indica el valor |
| Devuelve |
Puede usar los siguientes métodos para recuperar información de una instancia de InsertOneResult:
Método | Descripción |
|---|---|
| Indica los valores |
| Devuelve |
Nota
Si el método wasAcknowledged() retorna false, intentar acceder a los valores _id resultará en una excepción InvalidOperation. El driver no puede determinar estos valores si el servidor no reconoce la operación de guardado.
Información Adicional
Para obtener ejemplos de código ejecutables que demuestran cómo insertar documentos mediante el controlador Kotlin Sync, consulte Insertar documentos.
Documentación de la API
Para aprender más sobre cualquiera de los métodos o tipos analizados en esta guía, consulta la siguiente documentación de API: