Skip Returned Results

On this page

Overview

Examples
Using a FindIterable
Using Aggregation

Overview

In this guide, you can learn how to skip a specified number of returned results from read operations with the MongoDB Kotlin 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 FindFlow.

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:

val filter = Filters.empty()
val results = collection.aggregate(listOf(
    Aggregates.match(filter),
    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 }

This data is modeled with the following Kotlin data class:

data class PaintOrder(
    @BsonId val id: Int,
    val qty: Int,
    val color: String
)

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

val filter = Filters.empty()
val results = collection.find(filter)
    .sort(descending(PaintOrder::qty.name))
    .skip(5)
results.collect { println(it) }

PaintOrder(id=4, qty=6, color=white)
PaintOrder(id=1, qty=5, color=red)
PaintOrder(id=6, qty=3, color=pink)

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

val filter = Filters.empty()
val aggregate = listOf(
    Aggregates.match(filter),
    Aggregates.sort(descending(PaintOrder::qty.name)),
    Aggregates.skip(5)
)
val findFlow = collection.aggregate(aggregate)
findFlow.collect { println(it) }

PaintOrder(id=4, qty=6, color=white)
PaintOrder(id=1, qty=5, color=red)
PaintOrder(id=6, qty=3, color=pink)

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.

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.

val filter = Filters.empty()
val emptyQuery = listOf(
    Aggregates.match(filter),
    Aggregates.sort(descending(PaintOrder::qty.name)),
    Aggregates.skip(9)
)
val findFlow = collection.aggregate(emptyQuery)
findFlow.collect { println(it) }

MongoDB Kotlin Driver