Shallow Cache Reference

This page is the full reference for shallow caching in Readyset. For a conceptual overview, see Shallow Caching.

CREATE SHALLOW CACHE

Registers a query as a shallow (TTL-based) cache. Readyset stores the result set in memory and serves it directly to clients until the TTL expires, without building a materialized view.

CREATE SHALLOW CACHE POLICY TTL 30 SECONDS FROM
  SELECT * FROM products WHERE category_id = $1;

For the full grammar, including the POLICY, REFRESH, COALESCE, ALWAYS, and UNTIL WRITE options, see CREATE CACHE in the command reference.

Examples

Cache with a 30-second TTL and default refresh behavior (implicit 15-second on-demand refresh):

CREATE SHALLOW CACHE POLICY TTL 30 SECONDS FROM
  SELECT * FROM products WHERE category_id = $1;

Cache with a 60-second TTL and a 10-second on-demand refresh:

CREATE SHALLOW CACHE POLICY TTL 60 SECONDS REFRESH 10 SECONDS FROM
  SELECT * FROM sessions WHERE user_id = $1;

Cache with a 60-second TTL and a proactive 15-second scheduled refresh:

CREATE SHALLOW CACHE POLICY TTL 60 SECONDS REFRESH EVERY 15 SECONDS FROM
  SELECT count(*) FROM orders WHERE status = $1;

Cache with coalescing disabled and a name:

CREATE SHALLOW CACHE POLICY TTL 30 SECONDS COALESCE 0 SECONDS my_cache FROM
  SELECT * FROM inventory WHERE sku = $1;

Cache with sub-second TTL and mixed units:

CREATE SHALLOW CACHE POLICY TTL 5 SECONDS REFRESH 500 MILLISECONDS FROM
  SELECT * FROM leaderboard WHERE game_id = $1;

Cache that serves read-only-so-far transactions but proxies upstream after the first write in a transaction:

CREATE SHALLOW CACHE UNTIL WRITE FROM
  SELECT * FROM users WHERE id = $1;

DROP CACHE

DROP CACHE <query id>;

Removes a shallow cache (or any cache) by name or ID. After dropping, queries matching that cache are proxied to the upstream database. See the Command Reference for full details.

Metrics

The following Prometheus metrics are available for shallow caches. Each metric includes a query_id label identifying the cache.