Caching

Overview

Query result caching runs by default on GET /api/{project}/items/{collection} and GET /api/{project}/items/{collection}/{id}. It stores and reuses results. On a cache miss or if Redis becomes unreachable after startup, Monospace queries the connected data source instead.

Cache-relevant events can be diagnosed by including monospace::cache=trace in the value of the MONOSPACE_LOG environment variable.

Enable Caching

Configure a dedicated Redis or Valkey instance for Monospace:

redis:
  url: redis://cache.example.com:6379
  prefix: "monospace:" # default

# defaults:
cache:
  enabled: true
  include_status_header: false
  ttl: 5m
  max_entry_size: 8m

Unless caching is disabled, Monospace requires Redis-compatible storage for cache. See Configuration.

Cache is invalidated by mutations on any of the fields read by a query. Schema changes also invalidate cache.

Inspect Cache Status

Enable the Cache-Status response header to identify cache hits, misses, bypasses, and successful stores:

cache:
  include_status_header: true

This setting is disabled by default because it exposes information about cache operation. When CORS is enabled, Monospace automatically exposes Cache-Status to cross-origin browser clients.

Bypass Caching

Send one Cache-Control header with one of these exact values:

Cache-Control: no-cache, no-store
Cache-Control: no-store, no-cache
Cache-Control: no-cache
Cache-Control: no-store

Use one header with the exact lowercase spelling and spacing shown above. Each value bypasses both cache lookup and storage.

Limitations

• Monospace cannot detect writes made directly to a connected data source. Ordinary reads can remain stale until expiry, while a bypassed request reads live data.
• Connecting the same physical data source to multiple projects can similarly produce stale results. A mutation through one project does not currently invalidate cached results owned by another project.
• If a replica stops unexpectedly after committing a mutation but before invalidation completes, affected results can remain stale until expiry, eviction, or clearing. A bypassed request still reads live data.
• If caching is disabled then re-enabled, old results are not automatically invalidated. Before re-enabling caching, clear the old cache or configure a new Redis key prefix.

Configure Redis Memory

For a dedicated cache instance, Monospace can apply Redis memory settings on the operator's behalf:

redis:
  url: redis://cache.example.com:6379
  config_set:
    maxmemory: 100mb
    maxmemory-policy: volatile-lru

config_set applies server-wide settings. Configure memory and eviction outside Monospace when Redis is shared with other applications.

The volatile-lru example allows Redis to evict expiring cached results when it reaches maxmemory. Choose limits and an eviction policy that fit your deployment.

See Also

• Reading Data -- read item lists and individual items
• Query Engine -- understand query planning and execution
• Configuration -- configure Redis, cache limits, and TLS