Before you deploy
Redis is in the request path
- Startup depends on Redis. The router does not start while Redis is unreachable. See Redis.
- Writes are synchronous. The client response waits for each cache write. Keep Redis close to the router, and watch the write duration under Cache health.
- There is no cache-specific timeout. Without limits on the Redis URL, an unresponsive Redis holds every cacheable fetch for seconds. See Redis timeouts.
- Failures fall back to the subgraph. While Redis is down, every fetch goes to its subgraph. Your subgraphs must be able to take the full traffic.
Size Redis for the cache
- Set
maxmemoryand an eviction policy such asvolatile-ttlorallkeys-lru. Every entry has an expiry. - Every object of an entity fetch is its own key. An entity fetch for 100 distinct objects adds 100 keys. See Keys.
- Every index tag is a sorted set. With all indexes on, an entity entry is listed in at least two sets: its subgraph and its type.
Key cardinality
A key includes every variable value of the subgraph request. Operations with many distinct variable values, such as search terms or pagination cursors, create entries that are rarely read again. They cost a write on each miss and a lookup on each request. Use the store decision and the churn query to find such operations. Sendno-store from the subgraph for responses that are not worth caching.
In-memory provider
An in-memory storage provider exists, set withstorage.provider: 'memory'. It is not suitable for production. Each router replica has its own cache, nothing survives a restart, and an invalidation reaches only the replica it was sent to. Use Redis.
Secure the invalidation endpoint
Anyone with the shared key can empty the cache and push the full load onto your subgraphs. Rotate the key like any other credential. See Invalidation endpoint.Subgraph responsibilities
The cache trusts what subgraphs say about their responses.- Send a caching directive on every cacheable response. See What is stored.
- Name request headers in
Vary. A forwarded header that changes the answer must be listed inVary. Otherwise the first caller’s answer is served to everyone. See Varying responses. - Mark per-caller data
private, and configure aprivate_id. See Private responses. - Mark responses that depend on other credentials
private. See OnlyAuthorizationmakes a response private. - Report failures as failures. A
200with wrong data is stored. See Subgraph data is not validated.
Limitations
Subgraph data is not validated before storing
Data is stored as the subgraph returned it, before it is checked against the schema. A value of the wrong type, ornull in a non-null field, is stored. Every hit then returns the same error until the entry expires or is invalidated. This is a known issue.
Entities that do not exist are not cached
An object the subgraph returns asnull is not stored. A fetch that includes it is never a hit, so it reaches the subgraph on every request.
Batches are all or nothing
One missing object sends the whole entity fetch to the subgraph, including the cached objects. After an invalidation of one object, the next request for any batch containing it refetches the whole batch. See All or nothing per fetch.Merged entity fetches
Withengine.enable_multi_fetch, which is on by default, entity fetches can be merged into one request.
- Entries are not shared with plain entity fetches. How fetches are merged depends on the shape of the operation, so two operations that need the same objects can use different entries.
- Declared cache tags are dropped. Such entries can be invalidated by subgraph or type, but not by cache tag.
- One
Varycovers all aliases. The merged response’sVaryapplies to every alias. - Dependent fetches are skipped on failure. When the request for the uncached aliases fails, fetches that depend on the merged fetch are skipped, including those that need only cached aliases. Their fields are
nullwithout an error.
Only Authorization makes a response private
A subgraph request that carries a forwarded Authorization header makes the subgraph response private, unless it says public, s-maxage or must-revalidate. No other credential has this effect. A subgraph that authenticates with Cookie or a custom header, and sends max-age without private, has its answer stored as a shared entry and served to every caller. Such subgraphs must send private. See Authorization.
Varied headers changed by custom modules
For a subgraph response withVary, the router keys the entry by the header values it built, before custom modules run.
- If a module changes a varied header, the subgraph response is not stored.
Accept,Accept-EncodingandContent-Typeare not checked. If a module changes one of them based on other input, such as a client header the subgraph does not vary on, different requests can share an entry and get each other’s answers.
No stale serving or revalidation
Entries are served until they expire and never after. The cache never revalidates with the subgraph. See Lifetime.Clients can bypass the cache
Any client can sendCache-Control: no-cache to skip the cache, and these directives cannot be turned off. See Request directives.
Operations that are never cached
Mutations, subscriptions, WebSocket operations, file uploads and introspection are never cached. See Which fetches are cached.gRPC subgraphs and plugins are not supported
The response cache does not support gRPC subgraphs or router plugins. Nothing they return is stored.- Root fetches are not looked up. They report
not_cacheable. - Entity fetches are still looked up in the store on every request, which costs a round trip each. Their responses carry no
Cache-ControlorExpires, so they are never stored. They reportmisswith store decisionno_directive.
config.yaml
Cache-Control on the client response
- Without a cache control policy, the client response gets no
Cache-Controlfrom the cache. See Cache-Control of cached fetches. must-revalidateandproxy-revalidateare reported on a miss but not on a hit.stale-while-revalidateandstale-if-errorare never reported.- Batched operations receive no
Cache-Controlfrom the cache.
Response headers on hits
A hit has no subgraph response. Forwarded subgraph response headers, such asSet-Cookie, are absent, and subgraph.response.header is empty. Transport telemetry is missing too. See Per fetch.