Docs Home → Develop Applications → Python Drivers → PyMongo
Specify Documents to Return
On this page
Overview
In this guide, you can learn how to specify which documents to return from a read operation by using the following methods:
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.
Sample Data
The examples in this guide use the sample_restaurants.restaurants collection
from the Atlas sample datasets. To learn how to create a
free MongoDB Atlas cluster and load the sample datasets, see the Get Started with PyMongo.
Limit
To specify the maximum number of documents returned from a read operation,
call the limit() method.
The following example finds all restaurants that have a cuisine field value
of "Italian", and limits the results to 5 documents:
results = restaurants.find({ "cuisine" : "Italian"}).limit(5) for restaurant in results: print(restaurant["name"])
Isle Of Capri Resturant Italian Arturo'S Italian Patsy'S Italian Restaurant Italian Piccola Venezia Italian Roadhouse Restaurant Italian
You can also limit the number of returned documents by specifying the limit
parameter in your find() method:
results = restaurants.find({ "cuisine" : "Italian"}, limit=5) for restaurant in results: print(restaurant["name"])
Isle Of Capri Resturant Italian Arturo'S Italian Patsy'S Italian Restaurant Italian Piccola Venezia Italian Roadhouse Restaurant Italian
Tip
The preceding examples return the first five documents returned by the query, in no particular order. The following section describes how to return the documents in a specified sort order.
Sort
To return documents in a specified order, call the sort() method. The sort()
method takes two parameters: the field to sort the results by, and a sort direction. To
specify the sort direction, specify either pymongo.ASCENDING or
pymongo.DESCENDING. ASCENDING sorts values from lowest to highest, and
DESCENDING sorts them from highest to lowest. If you don't specify either
direction, the method defaults to sorting in ascending order.
The following example returns all documents with the cuisine value of
"Italian", sorted in ascending order:
results = restaurants.find({ "cuisine" : "Italian"}).sort("name", pymongo.ASCENDING) for restaurant in results: print(restaurant["name"])
(Lewis Drug Store) Locanda Vini E Olii 101 Restaurant And Bar 44 Sw Ristorante & Bar 900 Park A Voce ... Zucchero E Pomodori
You can also sort documents by specifying the sort parameter in your find()
method. The following example specifies the sort parameter to return the
results in the same order as the preceding example:
results = restaurants.find({ "cuisine" : "Italian"}, sort={"name": pymongo.ASCENDING} ) for restaurant in results: print(restaurant["name"])
(Lewis Drug Store) Locanda Vini E Olii 101 Restaurant And Bar 44 Sw Ristorante & Bar 900 Park A Voce ... Zucchero E Pomodori
Skip
To skip a specified number of documents before returning your query results,
call the skip() method and pass in the number of documents to skip. The
skip() method ignores the specified number of documents in your query
results and returns the rest.
The following example returns all documents that have a borough field value
of "Manhattan", and skips the first 10 documents:
results = restaurants.find({ "borough" : "Manhattan"}).skip(10) for restaurant in results: print(restaurant["name"])
Dorrian'S Red Hand Restaurant The Princeton Club Moran'S Chelsea La Parisienne Diner Jimmy'S Corner ...
You can also skip returned documents by using the skip
parameter of the find() method. The following example specifies the
same skip as the preceding example:
results = restaurants.find({ "borough" : "Manhattan"}, skip=10) for restaurant in results: print(restaurant["name"])
Dorrian'S Red Hand Restaurant The Princeton Club Moran'S Chelsea La Parisienne Diner Jimmy'S Corner ...
Combine Limit, Sort, and Skip
You can combine the limit(), sort(), and skip() methods in a single
operation. This allows you to set a maximum number of sorted documents to
return, skipping a specified number of documents before returning.
The following example returns documents with the cuisine value of
"Italian". The results are sorted in alphabetical order, skipping the first
10 documents:
results = restaurants.find({ "cuisine" : "Italian"}) \ .sort("name", pymongo.ASCENDING) \ .limit(5) \ .skip(10) for restaurant in results: print(restaurant["name"])
Acqua Acqua Restaurant Acqua Santa Acquista Trattoria Acquolina Catering
Note
The order in which you call these methods doesn't change the documents that are returned. The driver automatically reorders the calls to perform the sort and skip operations first, and the limit operation afterward.
You can also limit, sort, and skip results by specifying them as
parameters in the find() method. The following example specifies the
same query as the preceding example:
results = restaurants.find({ "cuisine" : "Italian"}, limit=5, sort={"name": pymongo.ASCENDING}, skip=10) for restaurant in results: print(restaurant["name"])
Acqua Acqua Restaurant Acqua Santa Acquista Trattoria Acquolina Catering
Additional Information
For more information about specifying a query, see Specify a Query.
For more information about retrieving documents, see Retrieve Data.
API Documentation
To learn more about any of the methods or types discussed in this guide, see the following API Documentation: