diff --git a/.changesets/docs_response_caching_faq_corrections.md b/.changesets/docs_response_caching_faq_corrections.md new file mode 100644 index 0000000000..484df1874e --- /dev/null +++ b/.changesets/docs_response_caching_faq_corrections.md @@ -0,0 +1,10 @@ +### Correct response caching documentation for schema updates and multi-root-field caching + +Updated the response caching FAQ to accurately describe caching behavior: + +- Clarified that schema updates generate new cache keys, so old entries won't receive cache hits (effectively expired from the user's perspective) rather than implying stale data might be served. +- Fixed the explanation of multi-root-field caching to correctly state that the router caches the entire subgraph response as a single unit, not separately per root field. +- Added clarification that the configured TTL is a fallback when subgraph responses don't include `Cache-Control: max-age` headers. +- Changed example TTL from `300s` to `5m` for better readability. + +By [@the-gigi-apollo](https://github.com/the-gigi-apollo) in https://github.com/apollographql/router/pull/8794 diff --git a/docs/source/routing/performance/caching/response-caching/faq.mdx b/docs/source/routing/performance/caching/response-caching/faq.mdx index 1e34a97448..fb504e3e6b 100644 --- a/docs/source/routing/performance/caching/response-caching/faq.mdx +++ b/docs/source/routing/performance/caching/response-caching/faq.mdx @@ -25,7 +25,7 @@ When you use the router's [authorization directives](/router/configuration/autho ### How do schema updates affect my cache? -Cached data remains valid across schema updates. When a new schema is deployed, the router immediately invalidates cache entries that depend on changed portions of the schema, ensuring responses always match the current schema. Cache entries for unchanged schema portions remain available. +The router doesn't remove cache entries when you update a schema. However, if a schema change affects the queries sent to subgraphs, the router generates new cache keys for those queries. As a result, old cache entries stop serving cache hits. They're effectively expired, although the data might still exist in storage until its TTL expires. Cache entries for unchanged query patterns remain available and continue to serve cache hits normally. ### Does the router cache error responses? @@ -63,7 +63,7 @@ Operations without tags eventually expire based on their TTL. You can invalidate ### How does caching work for operations with multiple root fields? -The router caches the entire operation response as a single unit. This means operations with overlapping root fields don't currently share cache entries—each unique operation gets its own entry. +The router caches the entire response from each subgraph request as a single unit. When an operation queries multiple root fields from the same subgraph, the router caches the complete response (containing all root fields) under a single cache entry. Operations with overlapping root fields don't share cache entries. The router creates a unique entry for each subgraph request based on the full query sent to the subgraph. This behavior does not apply to entity requests. ### When should I use invalidation vs. TTL-based caching? diff --git a/docs/source/routing/performance/caching/response-caching/quickstart.mdx b/docs/source/routing/performance/caching/response-caching/quickstart.mdx index 3ac109ca2c..420fb0be5a 100644 --- a/docs/source/routing/performance/caching/response-caching/quickstart.mdx +++ b/docs/source/routing/performance/caching/response-caching/quickstart.mdx @@ -31,6 +31,7 @@ To use response caching in GraphOS Router, you must set up: In `router.yaml`, configure `response_cache`: - Enable response caching globally - Configure Redis using the same conventions described in [distributed caching](/router/configuration/distributed-caching#redis-url-configuration) +- Configure a TTL either globally in `subgraph.all.ttl` or for each subgraph. The router requires a configured TTL to start. This TTL serves as a fallback. When a subgraph response includes a `Cache-Control` header with `max-age`, that value takes precedence. - Configure response caching per subgraph, with overrides per subgraph for disabling response caching and TTL For example: @@ -46,6 +47,7 @@ response_cache: subgraph: all: enabled: true + ttl: 5m # Required: fallback TTL when responses don't include Cache-Control headers # Configure Redis for all subgraphs redis: urls: ["redis://localhost:6379"]