(mongodb)=

MongoDB

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 {py:mod}~requests_cache.backends.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 {py:class}.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 {py:class}pymongo.mongo_client.MongoClient:

>>> backend = MongoCache(host='192.168.1.63', 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:

:::{dropdown} Screenshot :animate: fade-in-slide-down :color: primary :icon: file-media

:::

Expiration

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

Notes:

• 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 {ref}expiration settings <expiration>.
• 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 {ref}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 {py:class}.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))