MongoDB is a NoSQL document database. It stores data in collections of documents, which are more flexible and less strictly structured than tables in a relational database.

Use Cases#

MongoDB scales well and is a good option for larger applications. For raw caching performance, it is not quite as fast as redis, but may be preferable if you already have an instance running, or if it has a specific feature you want to use. See sections below for some relevant examples.

Usage Example#

Initialize with a MongoCache instance:

>>> from requests_cache import CachedSession, MongoCache
>>> session = CachedSession(backend=MongoCache())

Or by alias:

>>> session = CachedSession(backend='mongodb')

Connection Options#

This backend accepts any keyword arguments for pymongo.mongo_client.MongoClient:

>>> backend = MongoCache(host='', port=27017)
>>> session = CachedSession('http_cache', backend=backend)

Viewing Responses#

By default, responses are only partially serialized so they can be saved as plain MongoDB documents. Response data can be easily viewed via the MongoDB shell, Compass, or any other interface for MongoDB.

Here is an example response viewed in MongoDB for VSCode:



MongoDB natively supports TTL, and can automatically remove expired responses from the cache.


  • TTL is set for a whole collection, and cannot be set on a per-document basis.

  • It will persist until explicitly removed or overwritten, or if the collection is deleted.

  • Expired items are not guaranteed to be removed immediately. Typically it happens within 60 seconds.

  • If you want, you can rely entirely on MongoDB TTL instead of requests-cache expiration settings.

  • Or you can set both values, to be certain that you don’t get an expired response before MongoDB removes it.

  • If you intend to reuse expired responses, e.g. with Conditional Requests or stale_if_error, you can set TTL to a larger value than your session expire_after, or disable it altogether.

Examples: Create a TTL index:

>>> backend = MongoCache()
>>> backend.set_ttl(3600)

Overwrite it with a new value:

>>> backend = MongoCache()
>>> backend.set_ttl(timedelta(days=1), overwrite=True)

Remove the TTL index:

>>> backend = MongoCache()
>>> backend.set_ttl(None, overwrite=True)

Use both MongoDB TTL and requests-cache expiration:

>>> ttl = timedelta(days=1)
>>> backend = MongoCache()
>>> backend.set_ttl(ttl)
>>> session = CachedSession(backend=backend, expire_after=ttl)

Recommended: Set MongoDB TTL to a longer value than your CachedSession expiration. This allows expired responses to be eventually cleaned up, but still be reused for conditional requests for some period of time:

>>> backend = MongoCache()
>>> backend.set_ttl(timedelta(days=7))
>>> session = CachedSession(backend=backend, expire_after=timedelta(days=1))