Skip to content
Tutorials Center
My learning

Topics

Lesson 56 of 70 ยท Drivers and applications

Using MongoDB from Python

Use MongoDB from Python with PyMongo: MongoClient, insert, find, update, delete, cursors, ObjectId handling and a quick look at Motor for async code.

Python programs talk to MongoDB through a driver. The official synchronous driver is PyMongo, and its asynchronous sibling is Motor (and, in newer releases, PyMongo's own async API). A driver opens network connections, sends your filters and updates to the server, and turns the answers back into Python objects. The nice surprise is that a MongoDB document maps almost one to one onto a Python dict, so there is very little translation to learn.

MongoDB cannot run inside this page, so the PyMongo code below is shown in read-only blocks that you can paste into a real project. Each lesson section also has a runnable stand-in: a small class written in plain Python that stores dictionaries in a list and mimics the PyMongo method names, so you can practice the shape of the calls. If you have not met the practice idea yet, read The Practice Engine Used in This Tutorial first. For Python itself, see the Python tutorial.

The stand-ins here are real Python running in your browser, but they are not PyMongo. There is no network, no indexes, no real ObjectId and no durability. Everything shown in a read-only block is the real PyMongo API.

From Python to the server

Your code Dicts, lists, datetime.
MongoClient One shared connection pool.
Server Stores BSON documents.

The driver converts between dicts and BSON for you.

1 / 2

Install and connect

Install the driver with pip install pymongo. Then create one MongoClient for the whole program. The client owns a connection pool, so it is meant to be long-lived and shared, not created per request.

Python
from pymongo import MongoClient

client = MongoClient("mongodb://localhost:27017")
db = client["shop"]            # or client.shop
products = db["products"]      # or db.products

print(client.admin.command("ping"))   # {'ok': 1.0}

Indexing with square brackets works for any name, while attribute access (db.products) is shorter but fails for names that clash with Python attributes or contain dashes. MongoClient connects lazily: the constructor returns immediately, and the first real operation opens the connection. That is why a wrong host shows up as a timeout on your first query, not on the line that created the client. Connection string details, including Atlas mongodb+srv:// addresses, are in Installing MongoDB and Using mongosh.

CRUD with PyMongo

The method names match the shell and the other drivers, with snake_case spelling in Python: insert_one, insert_many, find_one, find, update_one, update_many, delete_one, delete_many and count_documents.

Python
result = products.insert_one({"name": "Lamp", "price": 25, "tags": ["home"]})
print(result.inserted_id)              # ObjectId('...')

products.insert_many([
    {"name": "Desk", "price": 180},
    {"name": "Chair", "price": 95},
])

doc = products.find_one({"name": "Desk"})          # a dict, or None
cheap = products.find({"price": {"$lt": 100}})     # a cursor

res = products.update_one({"name": "Lamp"}, {"$set": {"price": 22}})
print(res.matched_count, res.modified_count)

products.delete_one({"name": "Chair"})
print(products.count_documents({}))

Three details trip up newcomers. First, find_one returns None when nothing matches, so check before you index into the result. Second, filters and updates are the same documents you saw in earlier lessons (Finding Documents, Updating Documents); only the spelling of the method changes. Third, write methods return result objects (InsertOneResult, UpdateResult, DeleteResult) with attributes such as inserted_id, matched_count, modified_count and deleted_count, rather than the documents themselves.

Here is the stand-in. It is a Collection class over a list of dicts, with a tiny matcher that supports equality and $lt, $gt and $in. The calls you make read exactly like PyMongo.

Python A PyMongo-shaped collection

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The second update_one matches the lamp but modifies nothing, because the price is already 22, which is the same matched-versus-modified distinction real MongoDB reports.

Cursors

find() does not return a list. It returns a cursor: a lazy object that fetches documents from the server in batches as you iterate. You can chain sort, limit and skip on it before the query actually runs, and you can iterate it only once.

Python
cursor = products.find({"price": {"$gte": 20}}, {"name": 1, "_id": 0})
cursor = cursor.sort("price", -1).limit(5)      # sort takes (field, direction)

for doc in cursor:                               # fetched in batches
    print(doc["name"])

names = [d["name"] for d in products.find()]     # or list(cursor)

Two PyMongo-specific notes. sort takes a field and a direction (1 ascending, -1 descending, or the constants pymongo.ASCENDING and pymongo.DESCENDING), or a list of pairs for several keys, instead of the shell's object. Projection is the optional second argument of find. Calling list(cursor) on a huge result loads everything into memory, so iterate, or add a limit, when the result can be large. See Sorting, Limiting and Skipping for why big skip values are slow.

ObjectId handling

By default MongoDB gives every document an _id of type ObjectId, and PyMongo exposes it as bson.ObjectId. It is not a string, which causes the most common Python bug: comparing or querying with the string form.

Python
from bson import ObjectId

doc_id = products.insert_one({"name": "Lamp"}).inserted_id
print(type(doc_id))                 # <class 'bson.objectid.ObjectId'>
print(str(doc_id))                  # '65f1c0a2b7d4e8a1c3f9d012' (24 hex chars)

products.find_one({"_id": str(doc_id)})        # None: a string never equals an ObjectId
products.find_one({"_id": ObjectId(str(doc_id))})   # finds it

When ids travel through URLs or JSON, convert them with str(oid) on the way out and ObjectId(text) on the way in. ObjectId(text) raises bson.errors.InvalidId for malformed input, so wrap it in try/except in a web handler. Plain json.dumps cannot serialize an ObjectId or a datetime; use bson.json_util.dumps, or convert fields yourself. The structure of an id is explained in _id and ObjectId.

The second stand-in shows the pitfall. FakeObjectId is a class that wraps a counter and compares equal only to other FakeObjectId objects, like the real thing, plus a DuplicateKeyError raised when you insert an _id that already exists.

Python The string vs ObjectId trap

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Handling errors

PyMongo raises exceptions from pymongo.errors. The ones you meet first are DuplicateKeyError (a unique index or _id collision on insert), ServerSelectionTimeoutError (no reachable server, usually a wrong URI or a firewall), and BulkWriteError (details of a failed insert_many or bulk write). All derive from PyMongoError, so a broad except PyMongoError is a reasonable last resort in a request handler.

Python
from pymongo.errors import DuplicateKeyError, ServerSelectionTimeoutError

try:
    users.insert_one({"_id": 1, "email": "[email protected]"})
except DuplicateKeyError:
    print("already exists")
except ServerSelectionTimeoutError:
    print("database unreachable")

Async with Motor

Web frameworks built on asyncio (FastAPI, aiohttp) should not block while waiting for the database. Motor offers the same API with await on the operations that talk to the server, and async for on cursors:

Python
import asyncio
from motor.motor_asyncio import AsyncIOMotorClient

async def main():
    client = AsyncIOMotorClient("mongodb://localhost:27017")
    products = client["shop"]["products"]

    await products.insert_one({"name": "Lamp", "price": 25})
    async for doc in products.find({"price": {"$lt": 100}}):
        print(doc["name"])

asyncio.run(main())

Two rules carry over from the synchronous driver: create the client once, and remember that find() itself is not awaited (it only builds the cursor); the awaiting happens while you iterate. Recent PyMongo versions also include a native async client, so check the current driver documentation for which one to pick in a new project. Python's own concurrency model is covered in the Python tutorial.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should an application create one MongoClient and reuse it?

    A MongoClient manages a pool of connections. Creating one per request wastes connections and time; one long-lived client is the intended pattern.
  2. 2. products.find_one({"name": "Sofa"}) matches nothing. What does PyMongo return?

    find_one returns None when no document matches, so check the result before reading fields from it.
  3. 3. You query with {"_id": "65f1c0a2b7d4e8a1c3f9d012"} and get None, although the document exists. Most likely cause?

    ObjectId is its own BSON type. Convert the text with ObjectId(text) before querying.
  4. 4. What does find() return in PyMongo?

    find returns a cursor that fetches batches as you iterate. Use list(cursor) only when the result is small enough for memory.

Summary

  • PyMongo maps documents to Python dicts; Motor (or PyMongo's async client) adds await for asyncio programs.
  • Create one long-lived MongoClient; it connects lazily and pools connections.
  • Method names are snake_case versions of the shell's: insert_one, find_one, update_one, delete_many, count_documents.
  • find_one returns None on no match; find returns a lazy, single-use cursor; write methods return result objects.
  • _id is an ObjectId, not a string: convert with str() and ObjectId(text), and catch InvalidId.
  • Common errors: DuplicateKeyError, ServerSelectionTimeoutError, BulkWriteError.

Next, see how object-document mappers add structure in Mongoose and ODMs.