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, "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 strawberry birthday cakes" },
{ "_id": 3, "date": "2022-01-11", "orderTotal": 19.49, "description": "1 dozen strawberry 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": 10.99, "description": "1 bagel, 1 orange juice, 1 muffin" },
{ "_id": 6, "date": "2022-01-23", "orderTotal": 60.31, "description": "one large strawberry and chocolate cake" }

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 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 resembles the following:

{ "_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 strawberry birthday cakes" }
{ "_id": 3, "date": "2022-01-11", "orderTotal": 19.49, "description": "1 dozen strawberry cupcakes" }
...

Descending

To specify a descending sort, use the Sorts.descending() static factory method. Pass Sorts.descending() the name of the field 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, "date": "2022-01-23", "orderTotal": 60.31, "description": "one large strawberry and chocolate cake" }
{ "_id": 5, "date": "2022-01-23", "orderTotal": 10.99, "description": "1 bagel, 1 orange juice, 1 muffin" }
{ "_id": 4, "date": "2022-01-15", "orderTotal": 43.62, "description": "2 chicken lunches and a diet coke" }
...

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("date"), ascending("orderTotal"));
collection.find().sort(orderBySort);

The output of the preceding example resembles the following:

{ "_id": 5, "date": "2022-01-23", "orderTotal": 10.99, "description": "1 bagel, 1 orange juice, 1 muffin" }
{ "_id": 6, "date": "2022-01-23", "orderTotal": 60.31, "description": "one large strawberry and chocolate cake" }
{ "_id": 4, "date": "2022-01-15", "orderTotal": 43.62, "description": "2 chicken lunches and a diet coke" }
{ "_id": 3, "date": "2022-01-11", "orderTotal": 19.49, "description": "1 dozen strawberry cupcakes" }
{ "_id": 2, "date": "2022-01-11", "orderTotal": 83.87, "description": "two medium strawberry birthday cakes" }
{ "_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 our sorting fundamentals guide.

For more information, see the Sorts class API Documentation.