Client-side query caching for PyMongo

client-query-cache uses MongoDB change streams to asynchronously invalidate cached query results. It supports synchronous and asyncio applications without requiring a separate cache server.

%%{init: {"flowchart": {"diagramPadding": 75}}}%%
flowchart LR
    App["Python<br/>application"] -->|"Reads"| Cache["Client-side<br/>caching"]
    Cache -->|"Miss / bypass"| DB[("MongoDB")]
    DB -.->|"Change streams<br/>Async invalidation"| Cache

Cache hits are served from client-side memory, reducing read latency and database load in read-heavy applications.

The library is tested against real MongoDB replica sets, including concurrency stress tests, and automated checks guard its performance and memory use against regressions.

Results vary by workload and deployment. Measurements and methodology.

Caching requires MongoDB 8.0+ on a replica set or sharded cluster. Reads on standalone servers and older MongoDB versions run through PyMongo without caching.

Invalidation is asynchronous: a cached read can return a preceding value until the write's change-stream event is processed. Use PyMongo directly when a read must immediately observe a preceding write; see consistency.

Eligible cache misses read from the primary with majority read concern, even when the collection leaves read concern unspecified, so only majority-committed results enter the cache. Uncached PyMongo reads use the deployment's default read concern, normally local. The two usually perform alike, but while replication lags or data-bearing members are unavailable, a miss can return older data or fail where an uncached read would not. Majority admission does not make cache hits current: invalidation remains asynchronous. See bypass conditions.

Quick start

uv add client-query-cache

Or use pip install client-query-cache.

from pymongo import MongoClient

from client_query_cache import CacheManager

with (
    MongoClient("mongodb://localhost:27017") as client,
    CacheManager(client) as cache_manager,
):
    collection = client["client_query_cache_tutorial"]["items"]
    cached_collection = cache_manager.get_cached_collection(collection)
    collection.replace_one(
        {"_id": "example"}, {"_id": "example", "value": 42}, upsert=True
    )
    cached_collection.find_one({"_id": "example"})  # Reads from MongoDB.
    cached_collection.find_one({"_id": "example"})  # Repeated reads can use the cache.

References

Getting started · Benchmarks · Examples

MongoDB is a registered trademark of MongoDB, Inc. This project is independent and is not affiliated with or endorsed by MongoDB, Inc.