Builders

On this page

Overview

Why Use Builders?
Example Scenario
Using the MongoDB Shell
Without Using Builders
Using Builders
Available Builders

Overview

This section includes guides on how to use each of the available builders and demonstrates the utility that the Kotlin driver builder classes provide.

The Kotlin driver provides classes to simplify the process of performing CRUD operations and using the Aggregation API. The static utility methods allow you to build queries and other kinds of documents more efficiently.

Why Use Builders?

When you use builders classes, you leverage the following products:

The Kotlin compiler to find errors during development
The IDE for discovery, debugging, and code completion

When using builders, the Kotlin compiler and the IDE catch errors such as misspelled operators or missing parameters early on. If you use the MongoDB shell or plain Kotlin instead, you write operators as strings and get no visual indication of a problem, which pushes these errors to runtime instead of compile time.

By using builder classes, you can write operators as methods, so that your IDE instantly indicates whether your code has errors. While developing, your IDE can also show you methods that you can use and can complete your code with placeholder parameters.

Example Scenario

Suppose you want to send a marketing email to all users in the users collection that meet the following criteria:

Users in which the value of the gender field is "female"
Users in which the value of the age field is greater than 29

You also need your query to return only their email addresses.

The documents in the users collection are modeled by the following data class:

data class User(
    @BsonId
    val id: BsonObjectId = BsonObjectId(),
    val gender: String,
    val age: Int,
    val email: String,
)

Using the MongoDB Shell

The following code provides the command you use in the MongoDB Shell to perform the query:

collection.find({ "gender": "female", "age" : { "$gt": 29 }}, { "_id": 0, "email": 1 })

Without Using Builders

The following code provides the find operation you create without builders in the Kotlin driver:

data class Results(val email: String)
val 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)

In this case, you might easily include an error when writing the "\$gt" operator in the filter, but your IDE returns the relevant error only at runtime.

Using Builders

The following code provides the find operation you create by using builders in the Kotlin driver:

import com.mongodb.client.model.Filters
import com.mongodb.client.model.Projections

data class Results(val email: String)
val filter = Filters.and(Filters.eq(User::gender.name, "female"), Filters.gt(User::age.name, 29))
val projection = Projections.fields(Projections.excludeId(), Projections.include("email"))
val results = collection.find<Results>(filter).projection(projection)

Available Builders

Aggregates for building aggregation pipelines.
- Atlas Vector Search for using the Aggregates.vectorSearch() method to use the Atlas Vector Search feature.
Filters for building query filters.
Indexes for creating index keys.
Projections for building projections.
Sorts for building sort criteria.
Updates for building updates.

The Use Builders with Data Classes guide provides examples on how to use the preceding builders classes directly with data class properties. This guide might help to make your application more type-safe and improve Kotlin interoperability.

Back

Compound Operations

Aggregation