Docs Home → Develop Applications → MongoDB Drivers → Java
Sort Results
On this page
Overview
In this guide, you can learn how to use the sort operation to order your results from read operations with the MongoDB Java driver.
The sort operation orders the documents returned from your query by your specified sort criteria. Sort criteria are the rules you pass to MongoDB that describe how you would like your data to be ordered. 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
You should read this guide if you would like to:
Perform ascending sorts and descending sorts.
Combine sort criteria.
Sort on the text score of a text search.
The examples in this guide 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"}
Methods For Sorting
You can sort results retrieved by a query and you can sort results
within an aggregation pipeline. To sort your query results, use the
sort()
method of a FindIterable
instance. To sort your results within an
aggregation pipeline, use the Aggregates.sort()
static factory method. Both
of these methods receive objects that implement the Bson
interface as
arguments. For more information, see our API Documentation for the
BSON interface.
You can use the sort()
method of a FindIterable
instance as follows:
import static com.mongodb.client.model.Sorts.ascending; // <MongoCollection setup code here> collection.find().sort(ascending("_id"));
You can use the Aggregates.sort()
method within an aggregation pipeline
as follows:
import com.mongodb.client.model.Aggregates; import static com.mongodb.client.model.Sorts.ascending; // <MongoCollection setup code here> collection.aggregate(Arrays.asList(Aggregates.sort(ascending("_id"))));
The preceding code snippets sort the documents in the
sample collection from smallest to
largest value of the _id
field:
{"_id": 1, "letter": "c", "food": "coffee with milk"} {"_id": 2, "letter": "a", "food": "donuts and coffee"} {"_id": 3, "letter": "a", "food": "maple syrup"} ...
In the preceding code snippets, we specify our sort criteria using the Sorts
builder class. While it is possible to specify sort criteria using any class
that implements the Bson
interface, we recommend that you specify sort
criteria through the Sorts
builder. For more information on the Sorts
builder class, see our
guide on the Sorts builder.
For more information about the classes and interfaces in this section, see the following API Documentation:
Sorting Direction
The direction of your sort can either be ascending or descending. An ascending sort orders your results from smallest to largest. A descending sort orders your results from largest to smallest.
Here are some examples of data sorted in ascending order:
Numbers: 1, 2, 3, 43, 43, 55, 120
Dates: 1990-03-10, 1995-01-01, 2005-10-30, 2005-12-21
Words (ASCII): Banana, Dill, carrot, cucumber, hummus
Here are some examples of data sorted in descending order:
Numbers: 100, 30, 12, 12, 9, 3, 1
Dates: 2020-01-01, 1998-12-11, 1998-12-10, 1975-07-22
Words (reverse ASCII): pear, grapes, apple, Cheese
The following subsections show how to specify these sort criteria.
Ascending
To specify an ascending sort, use the Sorts.ascending()
static
factory method. Pass the Sorts.ascending()
method
the name of the field you need to sort in ascending order.
You can pass the sort()
method the output of the Sorts.ascending()
method to specify an ascending sort on a field as follows:
import static com.mongodb.client.model.Sorts.ascending; // <MongoCollection setup code here> collection.find().sort(ascending("<field name>"));
The preceding sort()
method returns a FindIterable
object that can iterate
over the documents in your collection, sorted from smallest to largest on the
specified field name.
In the following code example, we use the ascending()
method to sort the
sample collection
by the _id
field:
import static com.mongodb.client.model.Sorts.ascending; // <MongoCollection setup code here> List<Document> results = new ArrayList<>(); collection.find().sort(ascending("_id")).into(results); for (Document result : results) { System.out.println(result.toJson()); }
The output of the preceding code 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 the Sorts.descending()
method the name of the field you need to sort in descending order.
The following code snippet shows how to specify a descending sort on the
_id
field:
import static com.mongodb.client.model.Sorts.descending; // <MongoCollection setup code here> collection.find().sort(descending("_id"));
The preceding code snippet returns the documents in the sample collection in descending order:
{"_id": 6, "letter": "c", "food": "maple donut"} {"_id": 5, "letter": "a", "food": "milk and cookies"} {"_id": 4, "letter": "b", "food": "coffee with sugar"} ...
Handling Ties
A tie occurs when two or more documents have identical values in the field you are using to order your results. MongoDB does not guarantee sort order in the event of ties. For example, suppose we encounter a tie when applying a sort to the sample collection using the following code:
import static com.mongodb.client.model.Sorts.ascending; // <MongoCollection setup code here> collection.find().sort(ascending("letter"));
Since multiple documents that matched our query contain the value "a" for the field on which we perform the sort, the following documents could be returned in any order:
{"_id": 3, "letter": "a", "food": "maple syrup"} {"_id": 5, "letter": "a", "food": "milk and cookies"} {"_id": 2, "letter": "a", "food": "donuts and coffee"}
If you need to guarantee a specific sort order for documents that have fields with identical values, you can specify additional fields to sort on in the event of a tie.
We can specify an ascending sort on the letter
field followed by the
_id
field as follows:
import static com.mongodb.client.model.Sorts.ascending; // <MongoCollection setup code here> collection.find().sort(ascending("letter", "_id"));
The preceding code snippet returns the documents in the sample collection in the following order:
{"_id": 2, "letter": "a", "food": "donuts and coffee"} {"_id": 3, "letter": "a", "food": "maple syrup"} {"_id": 5, "letter": "a", "food": "milk and cookies"} {"_id": 4, "letter": "b", "food": "coffee with sugar"} {"_id": 1, "letter": "c", "food": "coffee with milk"} {"_id": 6, "letter": "c", "food": "maple donut"}
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.
In the following code snippet, we use the orderBy()
method to order our data
by performing a descending sort on the letter
field, and in the event of a
tie, by performing an ascending sort 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 preceding code snippet returns the documents in the sample collection in the following order:
{"_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 Search
You can specify the order of the results of a
text search by how closely the string values of
each result's fields specified by the collection's text index match your search
string. The text search assigns a numerical
text score to
indicate how closely each result matches the search string. Use the
Sorts.metaTextScore()
static factory method to build your sort criteria to
sort by the text score.
Important
Make Sure to Create a Text Index
You need a text index on your collection to perform a text search. See the server manual documentation for more information on how to create a text index.
In the following code example, we show how you can use the
Sorts.metaTextScore()
method to sort the results of a text
search on the sample collection.
The code example uses the Filters,
Indexes, and
Projections builders.
The code example performs the following actions:
Creates a text index for your sample collection on the
food
field. If you callcreateIndex()
specifying an index that already exists on the collection, the operation does not create a new index.Runs your text search for the phrase "maple donut".
Projects text scores into your query results as the
score
field.Sorts your results by text score (best match first).
import com.mongodb.client.model.Sorts; import com.mongodb.client.model.Projections; import com.mongodb.client.model.Filters; import com.mongodb.client.model.Indexes; // <MongoCollection setup code here> collection.createIndex(Indexes.text("food")); Bson metaTextScoreSort = Sorts.metaTextScore("score"); Bson metaTextScoreProj = Projections.metaTextScore("score"); String searchTerm = "maple donut"; Bson searchQuery = Filters.text(searchTerm); collection.find(searchQuery) .projection(metaTextScoreProj) .sort(metaTextScoreSort) .into(results); for (Document result : results) { System.out.println(result.toJson()); }
The output of the preceding code example should look something like this:
{"_id": 6, "letter": "c", "food": "maple donut", "score": 1.5} {"_id": 2, "letter": "a", "food": "donuts and coffee", "score": 0.75} {"_id": 3, "letter": "a", "food": "maple syrup", "score": 0.75}
Note
Text Search Behavior in MongoDB 4.4 or Later
The structure of text search has changed for MongoDB 4.4 or later. You no
longer need to project Projections.metaTextScore()
into your
FindIterable
instance in order to sort on the text score. In addition,
the field name you specify in a $meta
text score aggregation operation
used in a sort is ignored. This means that the field name argument you pass
to Sorts.metaTextScore()
is disregarded.
For more information about the classes in this section, see the following API Documentation:
For more information, see the Sorts class API Documentation. See the server manual documentation for more information on the $text query operator and the $meta aggregation pipeline operator.