Sort Results

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:

• FindIterable

• Aggregates

• Sorts

• BSON

• Document

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.

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

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());
}

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

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

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

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

{"_id": 3, "letter": "a", "food": "maple syrup"}
{"_id": 5, "letter": "a", "food": "milk and cookies"}
{"_id": 2, "letter": "a", "food": "donuts and coffee"}

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

{"_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"}

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);

{"_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.

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:

1. Creates a text index for your sample collection on the food field. If you call createIndex() specifying an index that already exists on the collection, the operation does not create a new index.

2. Runs your text search for the phrase "maple donut".

3. Projects text scores into your query results as the score field.

4. 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}

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

• Filters

• Indexes

• Projections

• MongoCollection

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.