Skip Returned Results

On this page

Overview

Examples
Using a FindIterable
Using Aggregation

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of the Java Driver.

Overview

In this guide, you can learn how to skip a specified number of returned results from read operations with the MongoDB Java driver.

You can skip results on the returned results of a query by using the skip() method. You can also skip documents at a specific stage in an aggregation pipeline by specifying a $skip aggregation stage.

The skip() method takes an integer that specifies the number of documents to omit from the beginning of the list of documents returned by the FindIterable.

You can use the skip() method to skip the first two documents as follows:

collection.find().skip(2);

Aggregates.skip() is an optional stage in the aggregation pipeline that specifies how many documents to omit from the beginning of the results of the prior stage.

You can use the Aggregates.skip() method to skip the first two documents as follows:

import com.mongodb.client.model.Aggregates;
collection.aggregate(Arrays.asList(Aggregates.match(), Aggregates.skip(2)));

Examples

The following example is about a paint store that sells eight different colors of paint. The best colors sell quicker than the other colors. One day, a customer asks what the three best-selling (lowest inventory) colors are. The paint store keeps track of inventory in the qty field in their paint_inventory collection:

{ "_id": 1, "color": "red", "qty": 5 }
{ "_id": 2, "color": "purple", "qty": 10 }
{ "_id": 3, "color": "blue", "qty": 9 }
{ "_id": 4, "color": "white", "qty": 6 }
{ "_id": 5, "color": "yellow", "qty": 11 }
{ "_id": 6, "color": "pink", "qty": 3 }
{ "_id": 7, "color": "green", "qty": 8 }
{ "_id": 8, "color": "orange", "qty": 7 }

To address the scenario, the paint store needs to query the paint_inventory collection with an empty filter, sort the documents by qty field and omit the first five results.

Using a FindIterable

import com.mongodb.client.model.Filters;
import com.mongodb.client.model.Sorts;
// <MongoCollection setup code here>
Bson filter = Filters.empty();
collection.find(filter)             
    .sort(Sorts.descending("qty"))        
    .skip(5)                       
    .forEach(doc -> System.out.println(doc.toJson()));

The find() method returns all documents.
The sort() method specifies documents to display from highest to lowest based on the qty field.
The skip() method specifies to omit the first five documents.

Using Aggregation

import com.mongodb.client.model.Filters;
import com.mongodb.client.model.Sorts;
import com.mongodb.client.model.Aggregates;
// <MongoCollection setup code here>
Bson filter = Filters.empty();
collection.aggregate(Arrays.asList(
    Aggregates.match(filter), 
    Aggregates.sort(Sorts.descending("qty")), 
    Aggregates.skip(5)))
    .forEach(doc -> System.out.println(doc.toJson()));

The match() stage returns all documents.
The sort() stage specifies documents to display from highest to lowest based on the qty field.
The skip() stage specifies to omit the first five documents.

The following shows the output of both preceding queries:

{ "_id": 4, "color": "white", "qty": 6 }
{ "_id": 1, "color": "red", "qty": 5 }
{ "_id": 6, "color": "pink", "qty": 3 }

After the paint store runs the query, they find the three best-selling colors are pink, red, and white.

Note

If the value of skip is greater than or equal to the number of matched documents for a query, that query returns no documents.

If the skip() method from the preceding example skips the first nine documents, no results would return since the specified quantity exceeds the number of matched documents.

Bson filter = Filters.empty();
collection.find(filter)             
    .sort(Sorts.descending("qty"))        
    .skip(9)                       
    .forEach(doc -> System.out.println(doc.toJson()));

Back

Sort Results

Limit the Number of Returned Results