Shallow Cache Reference

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

CREATE SHALLOW CACHE

CREATE SHALLOW CACHE
  [POLICY TTL <n> SECONDS [REFRESH [EVERY] <n> SECONDS]]
  [COALESCE <n> SECONDS]
  [ALWAYS]
  [<name>] FROM <SELECT_STATEMENT>

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.

Options

POLICY TTL <n> SECONDS

The lifetime of each cache entry, in seconds. Once an entry has not been accessed for this duration, it is considered stale and will be refreshed on the next access.

If omitted, Readyset uses the server default configured by --default-ttl-ms.

REFRESH <n> SECONDS

When a request hits a cache entry that is at least n seconds old, Readyset preemptively issues a background refresh against upstream. The current request receives the existing cached value immediately; the updated result is available for subsequent requests.

If REFRESH is omitted entirely (no REFRESH or REFRESH EVERY clause), Readyset applies an implicit refresh interval equal to half the TTL.

Must be less than the TTL.

REFRESH EVERY <n> SECONDS

Readyset proactively re-executes the query against upstream on a fixed schedule, regardless of whether any client has requested it. Automatic refreshes continue as long as the cache entry has not been evicted due to TTL expiration.

Must be less than the TTL.

COALESCE <n> SECONDS

The window during which concurrent requests for the same query and parameter values are coalesced on a cache miss. Only the first request is sent to upstream; the rest wait for its result. This prevents a thundering herd from hitting upstream simultaneously.

If omitted, Readyset uses the server default configured by --default-coalesce-ms. Set to 0 to disable coalescing for this cache.

ALWAYS

When specified, Readyset serves results from this cache even when the query is executed inside a transaction. By default, queries inside transactions are forwarded to the upstream database.

<name>

An optional name for the cache. If omitted, Readyset assigns an identifier automatically. The name can be used with DROP CACHE and SHOW CACHES.

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;

DROP CACHE

DROP CACHE <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.