Default consistency level for SpiceDB cached permission checks

Question

SpiceDB maintains a caching layer for relationship tuples and permission checks to reduce latency for repeated access patterns. When a read request omits a consistency token, the server may return a result retrieved from this cache, which can represent a permission state that does not include recent write operations. This behavior enables the fastest possible response but may produce stale results.

The platform offers the at_least_as_fresh_as consistency level, which accepts a Zookie or ZedToken to enforce that returned data is not older than a specified causal point. However, the default freshness guarantee when no token is supplied -- specifically how the server decides between cached and freshly computed results -- is not explicitly documented, creating ambiguity for operators seeking predictable freshness behavior.

What mechanism determines whether a cached result is served over a fresh computation when no consistency token is present?
Is there a server-side configuration to establish a minimum freshness baseline for all permission reads?
How does the default freshness behavior scale under high-frequency update workloads?

Tasadduq Burney · Answer

When a CheckPermission request is issued without a consistency token (ZedToken), SpiceDB defaults to a minimize-latency mode. In this mode, the server may serve results from its internal in-memory caches rather than guaranteeing that the result includes the most recent write operations.

How Cached Results are Determined
The decision to serve a cached result versus performing a fresh computation is governed by internal cache validity windows. If a permission check matches an entry in the dispatch or relationship cache that has not yet expired or been invalidated, the server returns that cached value. If the entry is missing or has passed its internal TTL (Time-to-Live), the server triggers a fresh read from the datastore and re-evaluates the permission.

Likely Behavior vs. Confirmed Facts

Aspect
      Confirmed Behavior
      Likely/Assumed Behavior

Consistency
      Omitting a token allows stale reads.
      Default staleness is bound by internal TTLs.

Control
      at_least_as_fresh_as enforces a causal point.
      No global "minimum freshness" toggle exists.

Scaling
      High write volume increases cache misses.
      Freshness improves as hit rates drop.

Operational Impact and Scaling
Under high-frequency update workloads, the default freshness behavior scales inversely with cache efficiency. Because frequent writes invalidate related cached entries, the server is forced to perform more fresh computations. While this increases datastore load and latency, it implicitly reduces the window of staleness for those specific permissions.

Verification Steps
To determine the actual staleness window in your specific environment and version, use the following scoped verification method:

Write a relationship tuple to SpiceDB.
  Immediately execute a CheckPermission call without a consistency token.
  Observe if the change is reflected. If not, repeat the call at intervals (e.g., 100ms, 500ms, 1s) until the change appears.
  Compare this against a call using a ZedToken from the write operation to confirm the latency gap.

Note: Because cache defaults can vary between SpiceDB releases, you should measure this behavior on your deployed version rather than relying on a fixed theoretical threshold.

Missing Diagnostic Detail
To provide a more precise recommendation on cache tuning, please specify the SpiceDB version currently in use, as cache invalidation logic and configuration flags have evolved across releases.

Default consistency level for SpiceDB cached permission checks

1 answer

How Cached Results are Determined

Likely Behavior vs. Confirmed Facts

Operational Impact and Scaling

Verification Steps

Missing Diagnostic Detail

Your perspective belongs here.

0 question comments

Aspect	Confirmed Behavior	Likely/Assumed Behavior
Consistency	Omitting a token allows stale reads.	Default staleness is bound by internal TTLs.
Control	`at_least_as_fresh_as` enforces a causal point.	No global "minimum freshness" toggle exists.
Scaling	High write volume increases cache misses.	Freshness improves as hit rates drop.