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:
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.