Limit the Number of Returned Results

On this page

Overview

Specify a Limit
Combining Skip and Limit

Overview

In this guide, you can learn how to limit the number of results returned from read operations with the MongoDB Kotlin driver.

Use limit() to cap the number of documents that a read operation returns. This instance method designates the maximum number of documents that a read operation can return. If there are not enough documents to reach the specified limit, it can return a smaller number. If you use limit() with the skip() instance method, the skip applies first and the limit only applies to the documents left over after the skip. For more information on the skip() method, see our guide on Skipping Returned Documents.

The following examples demonstrate, respectively, how to insert data into a collection, how to use limit() to restrict the number of returned documents, and how to combine limit() with skip() to further narrow the results returned from a query.

Sample Documents

The following sections feature examples that update this sample document:

{ "_id": 1, "title": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 }
{ "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462  }
{ "_id": 3, "title": "Atlas Shrugged", "author": "Rand", "length": 1088  }
{ "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104  }
{ "_id": 5, "title": "Cryptonomicon", "author": "Stephenson", "length": 918  }
{ "_id": 6, "title": "A Dance with Dragons", "author": "Martin", "length": 1104  }

This data is modeled with the following Kotlin data class:

data class Book(
    @BsonId val id: Int,
    val title: String,
    val author: String,
    val length: Int
)

Specify a Limit

The next example queries the collection to return the top three longest books. It first matches all the documents with the query, then sorts on the length field to return books with longer lengths before books with shorter lengths. Lastly, it limits the return value to 3 documents, and returns the following three documents, sorted by length:

val results = collection.find()
    .sort(descending("length"))
    .limit(3)
results.collect { println(it) }

  Book(id=2, title=Les Misérables, author=Hugo, length=1462)
  Book(id=6, title=A Dance with Dragons, author=Martin, length=1104)
  Book(id=4, title=Infinite Jest, author=Wallace, length=1104)

Tip

The order in which you call limit() and sort() does not matter because the find command always applies the sort first and the limit after it. The following two calls are equivalent:

    collection.find().sort(descending("length")).limit(3)
    collection.find().limit(3).sort(descending("length"))

Combining Skip and Limit

To see the next three longest books, append the skip() method to your find() call. The integer argument passed to skip() will determine how many documents the find operation returns. This operation returns the documents that describe the fourth through sixth longest books:

val results = collection.find()
    .sort(descending("length"))
    .skip(3)
    .limit(3)
results.collect { println(it) }

  Book(id=3, title=Atlas Shrugged, author=Rand, length=1088)
  Book(id=5, title=Cryptonomicon, author=Stephenson, length=918)
  Book(id=1, title=The Brothers Karamazov, author=Dostoyevsky, length=824)

You can combine skip() and limit() in this way to implement paging for your collection, returning only small subsets of the collection at one time.

Note

In order to ensure stable sorts across multiple queries, you must sort using a unique key (such as _id). Otherwise, a call to skip() and limit() may produce unpredictable results when combined with sort().

For example, consider the following data:

{ type: "computer", data: "1", serial_no: 235235 }
{ type: "computer", data: "2", serial_no: 235237 }
{ type: "computer", data: "3", serial_no: 235239 }
{ type: "computer", data: "4", serial_no: 235241 }

If you sorted by type alone, sort() does not guarantee the same order upon return. Appending skip() and limit() to the sort() could return different documents for different queries. In this case, sorting by data or serial_no would guarantee a stable sort, as both are unique keys.

For more information about the methods and classes mentioned in this guide, see the following API Documentation:

MongoDB Kotlin Driver