Para agentes de IA: hay un índice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las páginas están disponibles agregando .md a cualquier ruta URL.

Migrar desde KMongo

Esta página contiene una comparación de alto nivel de la mayoría de las formas en que difieren el controlador oficial MongoDB Kotlin y el controlador desarrollado por la comunidad KMongo. Puedes utilizar esta página para identificar los cambios que necesitas realizar para migrar del controlador KMongo obsoleto al controlador oficial de MongoDB Kotlin.

KMongo es una popular librería desarrollada por la comunidad para trabajar con MongoDB desde aplicaciones en Kotlin. Es un contenedor alrededor del driver de Java que fue creado antes que el driver oficial de Kotlin para servir las necesidades de la Community de Kotlin.

Importante

A partir de julio de 2023, KMongo ha sido marcado como obsoleto.

El controlador MongoDB para Kotlin es el único controlador de MongoDB para Kotlin oficialmente soportado y mantenido. Es desarrollado por el equipo de MongoDB.

Aunque ambos controladores soportan operaciones síncronas y asíncronas, los ejemplos en esta página utilizarán operaciones asíncronas basadas en corutinas.

El controlador Kotlin es el controlador oficial de MongoDB para Kotlin. Está desarrollado por el equipo de MongoDB y proporciona una API nativa para que las aplicaciones Kotlin se conecten a MongoDB y trabajen con datos. Se implementa envolviendo el MongoDB Java driver.

KMongo es una popular librería desarrollada por la comunidad para trabajar con MongoDB desde aplicaciones en Kotlin. Es un contenedor alrededor del driver de Java que fue creado antes que el driver oficial de Kotlin para servir las necesidades de la Community de Kotlin.

Importante

A partir de julio de 2023, KMongo ha sido marcado como obsoleto.

El controlador de Kotlin se desarrolló en colaboración con el creador de KMongo, Julien Buret, para ofrecer a los usuarios un controlador respaldado oficialmente.

El controlador oficial de Kotlin y KMongo tienen APIs generalmente similares. Las similitudes notables entre el controlador de Kotlin y KMongo incluyen:

  • Soporte para operaciones síncronas y basadas en corrutinas

  • Soporte usando clases de datos para representar documentos MongoDB

  • Compatibilidad con la serialización de KotlinX

  • Compatibilidad con la API CRUD de MongoDB y la API de agregación

Aunque el controlador oficial de Kotlin y KMongo son similares, existen algunas diferencias clave:

  • El driver oficial no tiene funcionalidad incorporada para reactor, rxjava2, Jackson, o GSON.

  • El driver oficial no admite comandos de shell de MongoDB.

Ambos drivers te permiten conectarte y comunicarte con clústeres de MongoDB desde una aplicación Kotlin.

Para conectar a un clúster de MongoDB utilizando el controlador de MongoDB Kotlin:

import com.mongodb.kotlin.client.coroutine.MongoClient data class Jedi(val name: String, val age: Int) // Replace the placeholder with your MongoDB deployment's connection stringval uri = CONNECTION_STRING_URI_PLACEHOLDER val mongoClient = MongoClient.create(uri) val database = mongoClient.getDatabase("test")// Get a collection of documents of type Jedival collection = database.getCollection<Jedi>("jedi")

Consulta la documentación Conéctese a MongoDB para obtener más información.

Ambos controladores proporcionan soporte para todas las API CRUD de MongoDB y operaciones de agregación.

Tip

Si estás acostumbrado a construir filtros de query utilizando la notación infija disponible en KMongo, también puedes usar esta notación para crear filtros en el driver oficial de Kotlin usando métodos de extensión del paquete mongodb-driver-kotlin-extensions. Selecciona la pestaña Kotlin Driver Extensions para ver un ejemplo que utilice esta sintaxis de query en el driver de Kotlin.

El MongoDB Kotlin Driver también proporciona funciones para todas las operaciones CRUD básicas:

// Insert a documentval jedi = Jedi("Luke Skywalker", 19)collection.insertOne(jedi) // Find a documentval luke = collection.find(Jedi::name.name, "Luke Skywalker")val jedis = collection.find(lt(Jedi::age.name, 30)).toList() // Update a documentval filter = Filters.eq(Jedi::name.name, "Luke Skywalker")val update = Updates.set(Jedi::age.name, 20)collection.updateOne(filter, update) // Delete a documentval filter = Filters.eq(Jedi::name.name, "Luke Skywalker")collection.deleteOne(filter)

Puedes compilar pipelines de agregación usando el método aggregate() y la función pipeline:

data class Results(val avgAge: Double) val resultsFlow = collection.aggregate<Results>( listOf( Aggregates.match(Filters.ne(Jedi::name.name, "Luke Skywalker")), Aggregates.group("\$${Jedi::name.name}", Accumulators.avg("avgAge", "\$${Jedi::age.name}")) ))resultsFlow.collect { println(it) }

Consulta la documentación de Operaciones CRUD y Agregación para obtener más información.

Ambos drivers brindan soporte para consultas de tipo seguro utilizando referencias de propiedad.

Tip

Si estás acostumbrado a construir filtros de query utilizando la notación infija disponible en KMongo, también puedes usar esta notación para crear filtros en el driver oficial de Kotlin usando métodos de extensión del paquete mongodb-driver-kotlin-extensions. Selecciona la pestaña Kotlin Driver Extensions para ver un ejemplo que utilice esta sintaxis de query en el driver de Kotlin.

El driver de MongoDB para Kotlin utiliza la API de desarrolladores para construir queries. Como alternativa, puedes usar la clase Document.

data class Person(val name: String, val email: String, val gender: String, val age: Int)data class Results(val email: String) val collection = database.getCollection<Person>("people") // Using Buildersval filter = and(eq("gender", "female"), gt("age", 29))val projection = fields(excludeId(), include("email"))val results = collection.find<Results>(filter).projection(projection) // Using Document classval filter = Document().append("gender", "female").append("age", Document().append("\$gt", 29))val projection = Document().append("_id", 0).append("email", 1)val results = collection.find<Results>(filter).projection(projection)

Para mapear una query de string de KMongo al driver de Kotlin, puedes usar la clase JsonObject.

val query = JsonObject("{\"name\": \"Gabriel Garc\\u00eda M\\u00e1rquez\"}")val jsonResult = collection.find(query).firstOrNull()

Para más información, consulta la siguiente documentación del controlador de Kotlin:

Ambos drivers admiten el uso de clases de datos de Kotlin y la clase Document para modelar los datos almacenados en una colección de MongoDB. La clase Document te permite modelar los datos representados en una colección de MongoDB en un formato flexible.

Puede utilizar clases de datos y clases Document para modelar datos con el controlador MongoDB Kotlin:

// With data classdata class Movie(val title: String, val year: Int, val rating: Float) val dataClassCollection = database.getCollection<Movie>("movies")val movieDataClass = dataClassCollection.findOneOrNull()val movieNameDataClass = movieDataClass.title // With Document classval documentCollection = database.getCollection<Movie>("movies")val movieDocument = documentCollection.findOneOrNull()val movieTitleDocument = movieDocument.getString("title")

Ambos controladores ofrecen soporte para serializar y deserializar objetos de datos en Kotlin hacia y desde BSON.

Puedes serializar las clases de datos en el driver de Kotlin utilizando tanto los códecs automáticos de clases de datos como la librería kotlinx.serialization. El controlador proporciona un eficiente Bson serializador que gestiona la serialización de objetos de Kotlin a datos BSON.

@Serializabledata class LightSaber( @SerialName("_id") // Use instead of @BsonId @Contextual val id: ObjectId?, val color: String, val qty: Int, @SerialName("brand") val manufacturer: String = "Acme" // Use instead of @BsonProperty)

Para obtener más información, consulta la documentación de Kotlin Serialization.

Si usas la clase Document para representar tu colección, puedes serializarla a JSON y EJSON mediante el método .toJson():

val document = Document("_id", 1).append("color", "blue") // Serialize to JSONdocument.toJson() // Serialize to EJSONval settings = JsonWriterSettings.builder().outputMode(JsonMode.STRICT).build()val json = doc.toJson(settings)

Para obtener más información sobre la serialización de datos con la clase Document, consulta la documentación de Formato de datos de documentos - JSON extendido.

Ambos controladores admiten operaciones síncronas y asíncronas.

El driver de MongoDB para Kotlin también tiene librerías separadas para operaciones síncronas y asíncronas. Sin embargo, el driver de Kotlin solo tiene funcionalidad incorporada para corrutinas como un paradigma asíncrono. El controlador de MongoDB Kotlin actualmente no proporciona soporte para otros paradigmas asíncronos, como Reactive Streams, Reactor o RxJava2.

Controlador
Paquete

sincronizar

com.mongodb.kotlin.client

corrutina

com.mongodb.kotlin.client.coroutine

A diferencia de KMongo, si deseas escribir código asíncrono, solo necesitas importar el paquete relevante.

Para escribir código síncrono:

import com.mongodb.kotlin.client.MongoClient // Instantiate your collectiondata class Jedi(val name: String, val age: Int)val uri = "<your-connection-string">val mongoClient = MongoClient.create(uri)val database = mongoClient.getDatabase("test")val collection = database.getCollection<Jedi>("jedi") // Synchronous operationsval jedi = Jedi("Luke Skywalker", 19)collection.insertOne(jedi)

Para escribir código de corrutinas asíncronas:

import com.mongodb.kotlin.client.coroutine.MongoClient // Instantiate your collectiondata class Jedi(val name: String, val age: Int)val uri = "<your-connection-string">val mongoClient = MongoClient.create(uri)val database = mongoClient.getDatabase("test")val collection = database.getCollection<Jedi>("jedi") runBlocking { // Async operations val jedi = Jedi("Luke Skywalker", 19) collection.insertOne(jedi)}

Ahora que ha aprendido sobre las diferencias entre KMongo y el controlador MongoDB Kotlin, consulta la Guía de inicio rápido para comenzar a utilizar el controlador KMongo Kotlin.