Sorts Builders

On this page

Overview

The Sorts Class
Ascending
Descending
Combining Sort Criteria
Text Score

Overview

In this guide, you can learn how to specify sort criteria for your queries using builders in the MongoDB Kotlin Driver.

Sort criteria are the rules MongoDB uses to sort your data. Some examples of sort criteria are:

Smallest number to largest number
Earliest time of day to latest time of day
Alphabetical order by first name

Builders are classes provided by the Kotlin driver that help you construct BSON objects. To learn more, see the builders guide.

You should read this guide if you want to learn how to use builders to specify sort criteria for your queries.

To learn the fundamentals of sorting in the Kotlin driver, see the sorting guide.

The examples on this page use a sample collection that contains the following documents:

{ "_id": 1, "date": "2022-01-03", "orderTotal": 17.86, "description": "1/2 lb cream cheese and 1 dozen bagels" },
{ "_id": 2, "date": "2022-01-11", "orderTotal": 83.87, "description": "two medium vanilla birthday cakes" },
{ "_id": 3, "date": "2022-01-11", "orderTotal": 19.49, "description": "1 dozen vanilla cupcakes" },
{ "_id": 4, "date": "2022-01-15", "orderTotal": 43.62, "description": "2 chicken lunches and a diet coke" },
{ "_id": 5, "date": "2022-01-23", "orderTotal": 60.31, "description": "one large vanilla and chocolate cake" },
{ "_id": 6, "date": "2022-01-23", "orderTotal": 10.99, "description": "1 bagel, 1 orange juice, 1 muffin" }

This data is modeled with the following Kotlin data class:

data class Order(
    @BsonId val id: Int,
    val date: String,
    val orderTotal: Double,
    val description: String,
)

The Sorts Class

The Sorts class is a builder that provides static factory methods for all sort criteria operators supported by MongoDB. These methods return a Bson object that you can pass to the sort() method of a FindFlow instance or to Aggregates.sort().

To learn more about the Aggregates class, see the Aggregates builder guide.

For more information about the classes and interfaces in this section, see the following API Documentation:

Ascending

To specify an ascending sort, use the Sorts.ascending() static factory method. Pass the name of the field you want to sort on to Sorts.ascending().

The following example sorts the documents in the sample collection by ascending order on the orderTotal field:

val resultsFlow = collection.find()
    .sort(Sorts.ascending(Order::orderTotal.name))
resultsFlow.collect { println(it) }

Order(id=6, date=2022-01-23, orderTotal=10.99, description=1 bagel, 1 orange juice, 1 muffin)
Order(id=1, date=2022-01-03, orderTotal=17.86, description=1/2 lb cream cheese and 1 dozen bagels)
Order(id=3, date=2022-01-11, orderTotal=19.49, description=1 dozen vanilla cupcakes)
Order(id=4, date=2022-01-15, orderTotal=43.62, description=2 chicken lunches and a diet coke)
Order(id=5, date=2022-01-23, orderTotal=60.31, description=one large vanilla and chocolate cake)
Order(id=2, date=2022-01-11, orderTotal=83.87, description=two medium vanilla birthday cakes)

Descending

To specify a descending sort, use the Sorts.descending() static factory method. Pass the name of the field you want to sort on to Sorts.descending().

The following example sorts the documents in the sample collection in descending order on the orderTotal field:

val resultsFlow = collection.find()
    .sort(Sorts.descending(Order::orderTotal.name))
resultsFlow.collect { println(it) }

Order(id=2, date=2022-01-11, orderTotal=83.87, description=two medium vanilla birthday cakes)
Order(id=5, date=2022-01-23, orderTotal=60.31, description=one large vanilla and chocolate cake)
Order(id=4, date=2022-01-15, orderTotal=43.62, description=2 chicken lunches and a diet coke)
Order(id=3, date=2022-01-11, orderTotal=19.49, description=1 dozen vanilla cupcakes)
Order(id=1, date=2022-01-03, orderTotal=17.86, description=1/2 lb cream cheese and 1 dozen bagels)
Order(id=6, date=2022-01-23, orderTotal=10.99, description=1 bagel, 1 orange juice, 1 muffin)

Combining Sort Criteria

To combine sort criteria, use the Sorts.orderBy() static factory method. This method constructs an object containing an ordered list of sort criteria. When performing the sort, if the previous sort criteria result in a tie, the sort uses the next sort criteria in the list to determine the order.

The following example sorts the documents in the sample collection in descending order on the date field, and in the event of a tie, ascending order on the orderTotal field:

val orderBySort = Sorts.orderBy(
    Sorts.descending(Order::date.name), Sorts.ascending(Order::orderTotal.name)
)
val results = collection.find().sort(orderBySort)
results.collect {println(it) }

Order(id=6, date=2022-01-23, orderTotal=10.99, description=1 bagel, 1 orange juice, 1 muffin)
Order(id=5, date=2022-01-23, orderTotal=60.31, description=one large vanilla and chocolate cake)
Order(id=4, date=2022-01-15, orderTotal=43.62, description=2 chicken lunches and a diet coke)
Order(id=3, date=2022-01-11, orderTotal=19.49, description=1 dozen vanilla cupcakes)
Order(id=2, date=2022-01-11, orderTotal=83.87, description=two medium vanilla birthday cakes)
Order(id=1, date=2022-01-03, orderTotal=17.86, description=1/2 lb cream cheese and 1 dozen bagels)

Text Score

You can sort text search results by their text score, a value that indicates how closely a search result matches your search string. To specify a sort by the text score of a text search, use the Sorts.metaTextScore() static factory method.

For a detailed example showing how to specify sort criteria using the Sorts.metaTextScore() method, see the text search section of the sorting guide.

For more information, see the Sorts class API Documentation.

Back

Projections Builders

Updates Builders