Sorts Builders

Overview

In this guide, you can learn how to specify sort criteria for your queries using builders in the MongoDB Java 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 MongoDB Java driver that help you construct BSON objects. To learn more, see our guide on builders.

You should read this guide if you would like to use builders to specify sort criteria for your queries.

If you want to learn the fundamentals of sorting in the MongoDB Java driver, consider reading our guide on sorting.

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

{"_id": 1, "letter": "c", "food": "coffee with milk"}
{"_id": 3, "letter": "a", "food": "maple syrup"}
{"_id": 4, "letter": "b", "food": "coffee with sugar"}
{"_id": 5, "letter": "a", "food": "milk and cookies"}
{"_id": 2, "letter": "a", "food": "donuts and coffee"}
{"_id": 6, "letter": "c", "food": "maple donut"}

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 FindIterable instance or to Aggregates.sort(). If you want to learn more about the Aggregates class, see our guide on the Aggregates builder.

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

• Sorts

• BSON

• FindIterable

• Aggregates

Ascending

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

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

import static com.mongodb.client.model.Sorts.ascending;
// <MongoCollection setup code here>
collection.find().sort(ascending("_id"));

The output of the preceding example should look something like this:

{"_id": 1, "letter": "c", "food": "coffee with milk"}
{"_id": 2, "letter": "a", "food": "donuts and coffee"}
{"_id": 3, "letter": "a", "food": "maple syrup"}
...

Descending

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

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

import static com.mongodb.client.model.Sorts.descending;
// <MongoCollection setup code here>
collection.find().sort(descending("_id"));

The preceding example should output something like this:

{"_id": 6, "letter": "c", "food": "maple donut"}
{"_id": 5, "letter": "a", "food": "milk and cookies"}
{"_id": 4, "letter": "b", "food": "coffee with sugar"}
...

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 leftmost sort criteria results 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 letter field, and in the event of a tie, ascending order on the _id field:

import static com.mongodb.client.model.Sorts.orderBy;
import static com.mongodb.client.model.Sorts.ascending;
import static com.mongodb.client.model.Sorts.descending;
// <MongoCollection setup code here>
Bson orderBySort = orderBy(descending("letter"), ascending("_id"));
collection.find().sort(orderBySort);

The output of the preceding example should look something like this:

{"_id": 1, "letter": "c", "food": "coffee with milk"}
{"_id": 6, "letter": "c", "food": "maple donut"}
{"_id": 4, "letter": "b", "food": "coffee with sugar"}
{"_id": 2, "letter": "a", "food": "donuts and coffee"}
{"_id": 3, "letter": "a", "food": "maple syrup"}
{"_id": 5, "letter": "a", "food": "milk and cookies"}

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 our sorting fundamentals guide.

For more information, see the Sorts class API Documentation.