Find Documents

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 tutorial.

Find One Document

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.

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"})

Find Multiple Documents

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:
...

all_restaurants = sample_restaurants.restaurants.find({})

Modify Find Behavior

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:

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.

Finding Invalid Documents in Collections

The following example shows how to identify invalid documents when iterating over a collection. Select the Synchronous or Asynchronous tab to see the corresponding code:

import bson
# Use RawBSONDocument to delay BSON decoding
raw_coll = collection.with_options(
    codec_options=collection.codec_options.with_options(
        document_class=bson.raw_bson.RawBSONDocument
    )
)
# Iterate through documents and check for BSON errors
for doc in raw_coll.find():
    try:
        bson.decode(doc.raw)
    except bson.errors.InvalidBSON as exc:
        print(f"Invalid document {exc}, raw bson: {doc.raw}")

import bson
# Use RawBSONDocument to delay BSON decoding
raw_coll = collection.with_options(
    codec_options=collection.codec_options.with_options(
        document_class=bson.raw_bson.RawBSONDocument
    )
)
# Iterate through documents and check for BSON errors
async for doc in raw_coll.find():
    try:
        bson.decode(doc.raw)
    except bson.errors.InvalidBSON as exc:
        print(f"Invalid document {exc}, raw bson: {doc.raw}")

Finding Invalid Documents in Command Responses

The following example shows how to handle invalid BSON in database command responses. Select the Synchronous or Asynchronous tab to see the corresponding code:

import bson
# Execute command with raw BSON options
res = client.admin.command(
    "serverStatus",
    codec_options=bson.raw_bson.DEFAULT_RAW_BSON_OPTIONS
)
# Check for BSON errors in the response
try:
    bson.decode(res.raw)
except bson.errors.InvalidBSON as exc:
    print(f"Invalid BSON found in serverStatus response {exc}, raw bson: {res.raw}")

import bson
# Execute command with raw BSON options
res = await client.admin.command(
    "serverStatus",
    codec_options=bson.raw_bson.DEFAULT_RAW_BSON_OPTIONS
)
# Check for BSON errors in the response
try:
    bson.decode(res.raw)
except bson.errors.InvalidBSON as exc:
    print(f"Invalid BSON found in serverStatus response {exc}, raw bson: {res.raw}")

API Documentation

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

• find()

• find_one()

• Collation

• Cursor