Docs Menu
Docs Home
/ / /
PyMongo
/

Retrieve Data

On this page

  • Overview
  • Sample Data
  • Find Documents
  • Find One Document
  • Find Multiple Documents
  • Modify Find Behavior
  • Additional Information
  • API Documentation

In this guide, you can learn how to use PyMongo, the MongoDB synchronous Python driver, to retrieve data from a MongoDB collection by using read operations. You can call the find() or find_one() method to retrieve documents that match a set of criteria.

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.

PyMongo includes two methods for retrieving documents from a collection: find_one() and find(). These methods take a query filter and return one or more matching documents. A query filter is an object that specifies the documents you want to retrieve in your query.

To learn more about query filters, see Specify a Query.

To find a single document in a collection, call the find_one() method and pass a query filter that specifies the criteria of the document you want to find. If more than one document matches the query filter, this method returns the first matching document from the retrieved results as a Python dictionary. If no documents match the query filter, the method returns None.

Tip

The find_one() method is useful when you know there's only one matching document, or you're only interested in the first match.

The following example uses the find_one() method to find the first document where the "cuisine" field has the value "Bakery":

restaurant = sample_restaurants.restaurants.find_one({"cuisine": "Bakery"})

Tip

Sort Order

The find_one() method returns the first document in natural order on disk if no sort criteria is specified.

To learn more about sorting, see the sort guide.

To find multiple documents in a collection, pass a query filter to the find() method that specifies the criteria of the documents you want to retrieve.

The following example uses the find() method to find all documents where the "cuisine" field has the value "Spanish":

cursor = sample_restaurants.restaurants.find({"cuisine": "Spanish"})

You can use a cursor to iterate over the documents returned by the find() method. A cursor is a mechanism that allows an application to iterate over database results while holding only a subset of them in memory at a given time. Cursors are useful when your find() method returns a large amount of documents.

You can iterate over the documents in a cursor by using a for-in loop, as shown in the following example:

cursor = sample_restaurants.restaurants.find({"cuisine": "Spanish"})
for restaurant in cursor:
...

Note

Find All Documents

To find all documents in a collection, pass an empty filter to the find() method:

all_restaurants = sample_restaurants.restaurants.find({})

You can modify the behavior of the find() and find_one() methods by passing named arguments to them. The following table describes the commonly used arguments:

Argument
Description
batch_size
Limits the number of documents to hold in a cursor at a given time.
collation
An instance of the Collation class that sets the collation options.
comment
A string to attach to the query. This can help you trace and interpret the operation in the server logs and in profile data. To learn more about query comments, see the $comment page.
hint
The index to use for the query.
max_time_ms
The maximum execution time on the server for this operation. If this time is exceeded, PyMongo aborts the operation and raises an ExecutionTimeout.

The following example uses the find() method to find all documents where the "cuisine" field has the value "Italian" and sets a maximum execution time of 10 seconds (10,000 milliseconds):

cursor = sample_restaurants.restaurants.find({"cuisine": "Italian"}, max_time_ms=10000)

For a full list of available arguments, see the API documentation for the find() method.

To learn more about query filters, see Specify a Query.

For runnable code examples of retrieving documents with PyMongo, see Read Data from MongoDB.

To learn more about any of the methods or types discussed in this guide, see the following API documentation:

Back

Specify a Query