Query Caching

causet-query-service can cache query results in Redis when you set cache_ttl_seconds on a query definition.

Configuration

queries:
  artist_leaderboard_top10:
    from: artist_leaderboard
    fields:
      - artist_id
      - artist_name
      - attend_count
    order_by:
      attend_count: desc
    limit: 10
    cache_ttl_seconds: 30

The cache key includes platform, application, fork, query name, and serialized input params. Identical calls within the TTL window skip PostgreSQL.

Staleness

Cached results may be stale by up to:

cache_ttl_seconds — Redis TTL
Projection lag — time between ledger commit and projection UPSERT

The cache is not invalidated when a projection updates. For leaderboards and counters this is usually acceptable. For inventory or financial data, leave caching disabled or use a very short TTL.

When to cache

Good candidates	Poor candidates
Leaderboards	Real-time inventory
Public directory listings	Account balances
Aggregate dashboards	”Did my write succeed?” checks
Rarely-changing reference data	Per-user notification counts (if freshness matters)

When not to cache

Queries called immediately after a write where the caller expects to see the new row
Queries with highly unique input params (cache hit rate near zero)
Security-sensitive reads where every call must hit the database

Next steps

Concept — eventual consistency on the read path
Best Practices — designing for stale reads
DSL: queries — query DSL reference

Aggregates Best Practices