Specify Documents to Return

Overview

In this guide, you can learn how to specify which documents to return from a read operation by chaining the following methods to the find() method:

• limit(): Specifies the maximum number of documents to return from a query

• sort(): Specifies the sort order for the returned documents

• skip(): Specifies the number of documents to skip before returning query results

val database: MongoDatabase = mongoClient.getDatabase("sample_restaurants")
val collection: MongoCollection[Document] = database.getCollection("restaurants")

Limit

To specify the maximum number of documents returned from a read operation, use the limit() method provided by the FindObservable class. After calling the find() method, chain the limit() method to modify the behavior of the operation.

The following example finds all restaurants that have a cuisine field value of "Italian" and limits the results to 5 documents:

val filter = equal("cuisine", "Italian")
collection.find(filter).limit(5).subscribe((doc: Document) => println(doc.toJson()),
                            (e: Throwable) => println(s"There was an error: $e"))

{"_id": {"$oid": "..."}, ... , "name": "Isle Of Capri Resturant", "restaurant_id": "40364373"}
{"_id": {"$oid": "..."}, ... , "name": "Marchis Restaurant", "restaurant_id": "40364668"}
{"_id": {"$oid": "..."}, ... , "name": "Crystal Room", "restaurant_id": "40365013"}
{"_id": {"$oid": "..."}, ... , "name": "Forlinis Restaurant", "restaurant_id": "40365098"}
{"_id": {"$oid": "..."}, ... , "name": "Angelo Of Mulberry St.", "restaurant_id": "40365293"}

Sort

To return documents in a specified order, use the sort() method provided by the FindObservable class. After calling the find() method, chain the sort() method to modify the behavior of the operation.

When calling sort(), pass the field to sort the results by and the sort direction. You can use the ascending() method to sort values from lowest to highest, or the descending() method to sort them from highest to lowest.

The following example returns all documents that have a cuisine field value of "Italian", sorted in ascending order of name field values:

val filter = equal("cuisine", "Italian")
collection.find(filter).sort(ascending("name")).subscribe((doc: Document) => println(doc.toJson()),
                            (e: Throwable) => println(s"There was an error: $e"))

{"_id": {"$oid": "..."}, ... , "name": "44 Sw Ristorante & Bar", "restaurant_id": "40698807"}
{"_id": {"$oid": "..."}, ... , "name": "900 Park", "restaurant_id": "41707964"}
{"_id": {"$oid": "..."}, ... , "name": "A Voce", "restaurant_id": "41434084"}
...
{"_id": {"$oid": "..."}, ... , "name": "Zucchero E Pomodori", "restaurant_id": "41189590"}

Skip

To skip a specified number of documents before returning your query results, use the skip() method provided by the FindObservable class. After calling the find() method, chain the skip() method to modify the behavior of the operation.

The following example returns all documents that have a borough field value of "Manhattan" and skips the first 10 documents:

val filter = equal("borough", "Manhattan")
collection.find(filter).skip(10).subscribe((doc: Document) => println(doc.toJson()),
                            (e: Throwable) => println(s"There was an error: $e"))

{"_id": {"$oid": "..."}, ... , "name": "Cafe Metro", "restaurant_id": "40363298"}
{"_id": {"$oid": "..."}, ... , "name": "Lexler Deli", "restaurant_id": "40363426"}
{"_id": {"$oid": "..."}, ... , "name": "Domino'S Pizza", "restaurant_id": "40363644"}
...

Combine Limit, Sort, and Skip

You can chain the limit(), sort(), and skip() methods to a single find() method call. This allows you to set a maximum number of sorted documents to return from the read operation, skipping a specified number of documents before returning.

The following example returns 5 documents that have a cuisine value of "Italian". The results are sorted in ascending order by the name field value, skipping the first 10 documents:

val filter = equal("cuisine", "Italian")
collection.find(filter)
          .limit(5)
          .skip(10)
          .sort(ascending("name"))
          .subscribe((doc: Document) => println(doc.toJson()),
                    (e: Throwable) => println(s"There was an error: $e"))

{"_id": {"$oid": "..."}, ... , "name": "Acqua", "restaurant_id": "40871070"}
{"_id": {"$oid": "..."}, ... , "name": "Acqua Restaurant", "restaurant_id": "41591488"}
{"_id": {"$oid": "..."}, ... , "name": "Acqua Santa", "restaurant_id": "40735858"}
{"_id": {"$oid": "..."}, ... , "name": "Acquista Trattoria", "restaurant_id": "40813992"}
{"_id": {"$oid": "..."}, ... , "name": "Acquolina Catering", "restaurant_id": "41381423"}

Additional Information

For more information about retrieving documents, see the Retrieve Data guide.

For more information about specifying a query, see the Specify a Query guide.