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

database = client.use('sample_restaurants')
collection = database[:restaurants]

Limit

To specify the maximum number of documents returned from a read operation, apply the limit option to the operation. You can set this option by chaining the limit setter method to the find method.

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

filter = { cuisine: 'Italian' }
collection.find(filter)
          .limit(5)
          .each { |doc| puts doc }

{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Philadelhia Grille Express",
"restaurant_id"=>"40364305"}
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Isle Of Capri Restaurant",
"restaurant_id"=>"40364373"}
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Marchis Restaurant",
"restaurant_id"=>"40364668"}
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Crystal Room",
"restaurant_id"=>"40365013"}
{"_id"=>BSON::ObjectId('...'), ... , name"=>"Forlinis Restaurant",
"restaurant_id"=>"40365098"}

Sort

To return documents in a specified order, apply the sort option to the read operation. You can set this option by chaining the sort setter method to the find method.

When calling sort, pass the field to sort the results by and the sort direction. A sort direction value of 1 sorts values from lowest to highest, and a value of -1 sorts 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:

filter = { cuisine: 'Italian' }
collection.find(filter)
          .sort(name: 1)
          .each { |doc| puts doc }

{"_id"=>BSON::ObjectId('...'), ... , "name"=>"(Lewis Drug Store) Locanda Vini E Olii",
"restaurant_id"=>"40804423"}
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"101 Restaurant And Bar",
"restaurant_id"=>"40560108"}
...
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Zucchero E Pomodori",
"restaurant_id"=>"41189590"}

Skip

To skip a specified number of documents before returning your query results, apply the skip option to the read operation. You can set this option by chaining the skip setter method to the find method.

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

filter = { borough: 'Manhattan' }
collection.find(filter)
          .skip(10)
          .each { |doc| puts doc }

{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Cafe Metro", "restaurant_id"=>"40363298"}
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Lexler Deli", "restaurant_id"=>"40363426"}
{"_id"=>BSON::ObjectId('...'), ... , "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:

filter = { cuisine: 'Italian' }
collection.find(filter)
          .limit(5)
          .skip(10)
          .sort(name: 1)
          .each { |doc| puts doc }

{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Acqua", "restaurant_id"=>"40871070"}
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Acqua Restaurant",
"restaurant_id"=>"41591488"}
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Acqua Santa", "restaurant_id"=>"40735858"}
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Acquista Trattoria",
"restaurant_id"=>"40813992"}
{"_id"=>BSON::ObjectId('...'), ... , "name"=>"Acquolina Catering", "restaurant_id"=>"41381423"}

Additional Information

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