Quick Start

Choose the java driver

Do you need to use the sync or the async driver?

If you don't know, start with the sync driver and add this dependency to your project:

• with Maven

<dependency>
  <groupId>org.litote.kmongo</groupId>
  <artifactId>kmongo</artifactId>
  <version>5.1.0</version>
</dependency>

• or Gradle

(Kotlin)

implementation("org.litote.kmongo:kmongo:5.1.0")

(Groovy)

implementation 'org.litote.kmongo:kmongo:5.1.0'

Starting from 4.0, minimum supported jvm is now 1.8 (was 1.6). You have to set the property jvmTarget to 1.8 (or more) in your gradle or maven descriptor

And start coding

Async driver support

KMongo can use the synchronous or the asynchronous java driver. For the asynchronous driver, reactive streams style, Kotlin Coroutines or RxJava2 are supported.

Reactive Streams style

• with Maven

<dependency>
  <groupId>org.litote.kmongo</groupId>
  <artifactId>kmongo-async</artifactId>
  <version>5.1.0</version>
</dependency>

• or Gradle

(Kotlin)

implementation("org.litote.kmongo:kmongo-async:5.1.0")

(Groovy)

implementation 'org.litote.kmongo:kmongo-async:5.1.0'

Kotlin Coroutines

• with Maven

<dependency>
  <groupId>org.litote.kmongo</groupId>
  <artifactId>kmongo-coroutine</artifactId>
  <version>5.1.0</version>
</dependency>

• or Gradle (Kotlin)

(Kotlin)

implementation("org.litote.kmongo:kmongo-coroutine:5.1.0")

(Groovy)

implementation 'org.litote.kmongo:kmongo-coroutine:5.1.0'

Reactor

<dependency>
  <groupId>org.litote.kmongo</groupId>
  <artifactId>kmongo-reactor</artifactId>
  <version>5.1.0</version>
</dependency>

• or Gradle

(Kotlin)

implementation("org.litote.kmongo:kmongo-reactor:5.1.0")

(Groovy)

implementation 'org.litote.kmongo:kmongo-reactor:5.1.0'

RxJava2

• with Maven

<dependency>
  <groupId>org.litote.kmongo</groupId>
  <artifactId>kmongo-rxjava2</artifactId>
  <version>5.1.0</version>
</dependency>

• or Gradle

(Kotlin)

implementation("org.litote.kmongo:kmongo-rxjava2:5.1.0")

(Groovy)

implementation 'org.litote.kmongo:kmongo-rxjava2:5.1.0'

Object Mapping Engine

By default, Jackson engine is used. You can use POJO Codec engine by adding a -native suffix to the artifactId, or Kotlinx Serialization by adding a -serialization suffix to the artifactId.

For example, replace kmongo by kmongo-native or kmongo-serialization for the sync driver For the coroutine driver, replace kmongo-coroutine by kmongo-coroutine-native or kmongo-coroutine-serialization . You can read more about the mapping engine in the dedicated chapter.

Let's Start Coding

With the sync driver

import org.litote.kmongo.* //NEEDED! import KMongo extensions

data class Jedi(val name: String, val age: Int)

val client = KMongo.createClient() //get com.mongodb.MongoClient new instance
val database = client.getDatabase("test") //normal java driver usage
val col = database.getCollection<Jedi>() //KMongo extension method
//here the name of the collection by convention is "jedi"
//you can use getCollection<Jedi>("otherjedi") if the collection name is different

col.insertOne(Jedi("Luke Skywalker", 19))

val yoda : Jedi? = col.findOne(Jedi::name eq "Yoda")

(...)

Asynchronously with Coroutines

import org.litote.kmongo.reactivestreams.*  //NEEDED! import KMongo reactivestreams extensions
import org.litote.kmongo.coroutine.* //NEEDED! import KMongo coroutine extensions

data class Jedi(val name: String, val age: Int)

val client = KMongo.createClient().coroutine //use coroutine extension
val database = client.getDatabase("test") //normal java driver usage
val col = database.getCollection<Jedi>() //KMongo extension method

//async now
runBlocking {
    col.insertOne(Jedi("Luke Skywalker", 19))

    val yoda : Jedi? = col.findOne(Jedi::name eq "Yoda")

    (...)
}

With kotlinx.serialization

import org.litote.kmongo.* //NEEDED! import KMongo extensions

@Serializable //you need to annotate each class you want to persist
data class Jedi(val name: String, val age: Int, val firstAppearance: StarWarsFilm)   

@Serializable
data class StarWarsFilm(
val name: String,             
//annotate with @Contextual the types that have already serializers - look at kotlinx.serialization documentation
@Contextual val date: LocalDate
)

val client = KMongo.createClient() //get com.mongodb.MongoClient new instance
val database = client.getDatabase("test") //normal java driver usage
val col = database.getCollection<Jedi>() //KMongo extension method
//here the name of the collection by convention is "jedi"
//you can use getCollection<Jedi>("otherjedi") if the collection name is different

col.insertOne(Jedi("Luke Skywalker", 19, StarWarsFilm("A New Hope", LocalDate.of(1977, Month.MAY, 25))))

val yoda : Jedi? = col.findOne(Jedi::name eq "Yoda")

(...)

KDoc

The KMongo API documentation in KDoc format is available:

• KMongo
• KMongo coroutine
• KMongo RXJava2