Overview
En esta guía, puede aprender a utilizar el controlador Kotlin Sync para agregar documentos a una colección MongoDB realizando 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 insertOne() y insertMany() métodos.
Datos de muestra
Los ejemplos de esta guía utilizan la colección sample_restaurants.restaurants de Conjuntos de datos de muestra de Atlas. Para aprender a crear una implementación gratuita de MongoDB y cargar los conjuntos de datos de muestra, consulte la guía de introducción a MongoDB.
Los documentos de esta colección están modelados por la siguiente clase de datos de Kotlin:
data class Restaurant(val name: String, val borough: String)
El _id campo
En una colección MongoDB, cada documento debe contener un _id campo 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.Puede permitir que el controlador genere automáticamente un valor
ObjectIdúnico para cada documento_id. Si no establece manualmente un valor_idpara un documento, el controlador rellena el campo con unObjectId.
A menos que pueda garantizar la singularidad, recomendamos dejar que el controlador genere automáticamente valores _id.
Nota
Errores de _id duplicados
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 _id campo, consulte la guía Índices únicos en el manual de MongoDB Server.
Para obtener más información sobre la estructura y las reglas de los documentos, consulte la guía Documentos en el manual del servidor MongoDB.
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 MongoDB, utilice el método insertMany() y pase una lista de 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 especifica ninguna opción, el controlador realiza la operación de inserción con la configuración predeterminada. Pase las opciones como último parámetro al método insertOne().
La siguiente tabla describe los métodos de configuración que puede utilizar para configurar una instancia 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 configurar los ajustes anteriores en el método insertMany() configurando una instancia InsertManyOptions. También puede usar el método setter ordered() para especificar el orden en que el controlador inserta los 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. |
Pase opciones como último parámetro al método insertMany().
Ejemplo de modificación 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 usa el método insertMany() para agregar 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 InsertOneResult y el método insertMany() devuelve una instancia InsertManyResult.
Puede utilizar los siguientes métodos para recuperar información de una instancia InsertOneResult:
Método | Descripción |
|---|---|
| Indica el valor |
| Devuelve |
Puede utilizar los siguientes métodos para recuperar información de una instancia InsertOneResult:
Método | Descripción |
|---|---|
| Indica los valores |
| Devuelve |
Nota
Si el método wasAcknowledged() devuelve false, al intentar acceder a los valores _id se genera una excepción InvalidOperation. El controlador no puede determinar estos valores si el servidor no confirma la operación de escritura.
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: