GraphQL cache guide for efficient data fetching

A GraphQL cache stores query results so your application can serve data instantly on repeat requests — without hitting the database or API again. Because GraphQL uses a single endpoint and POST requests by default, standard HTTP caching does not apply. You need a deliberate strategy: client-side normalized caches (Apollo Client, urql, Relay), server-side response caches (Redis, in-memory), and optionally edge caching via CDN with Automatic Persisted Queries. Done right, caching cuts response times by 80–90% and slashes backend load significantly.

What this guide covers

This guide is for developers who already use GraphQL and want to move beyond naive fetch-every-time patterns. You will learn how client-side normalized caching works in Apollo Client, how to add server-side response caching with the Envelop plugin system, how to enable CDN caching through Automatic Persisted Queries, and how to design a cache invalidation strategy that does not break your data consistency. Each section includes practical code examples you can adapt immediately.

Understanding the fundamentals of GraphQL caching

Caching temporarily stores the result of an expensive operation so that identical future requests can be answered instantly from that stored copy. In GraphQL applications, “expensive” usually means a database query, a downstream REST call, or a complex resolver chain. Avoiding that work on the second request is the entire point.

GraphQL caching is harder than REST caching for one structural reason: all queries go through the same URL using POST. HTTP caches — browsers, CDNs, reverse proxies — key on the URL and only cache GET requests by default. With GraphQL, two entirely different queries land on POST /graphql with the same URL, so the cache cannot distinguish them without reading the request body. This requires purpose-built solutions at every layer.

The flexibility that makes GraphQL powerful also creates caching complexity. A single query can request data from multiple resources, with varying field selections and nested relationships. Two queries might request similar data but with different field combinations, making it challenging to determine when cached data can be reused.

Effective GraphQL caching involves multiple layers working together: client-side normalized caches that store and reuse query results locally, server-side response caching that prevents redundant computation, and intermediate layers like CDNs that serve cached responses closer to users geographically.

REST vs GraphQL caching

REST APIs are inherently cacheable because they use HTTP GET requests with predictable URLs, allowing browsers, CDNs, and proxy servers to cache responses using Cache-Control and ETag headers without any extra configuration.

In REST, each endpoint typically represents a specific resource, making cache invalidation relatively straightforward. When a resource changes, you invalidate its URL. GraphQL’s single endpoint means all queries share the same URL, so cache keys must be derived from query content — usually a hash of the query string plus variables.

The trade-off is complexity versus precision. REST caching is simpler to implement out of the box, but GraphQL caching can be more efficient by enabling fine-grained, field-level invalidation based on which specific data actually changed.

Key components of an effective caching strategy

An effective GraphQL caching strategy requires four things working together: unique object identifiers, cache normalization, TTL policies, and a clear invalidation approach.

Unique object identifiers are the foundation. Unlike REST where resources are identified by URL, GraphQL requires globally unique IDs for each object to enable normalized caching. Every type should expose a consistent id field — UUIDs or composite keys that include type information work well.

Cache normalization stores objects by their unique identifiers rather than by query structure. When a query requests a user with ID “123”, the cache stores that user object under the key “User:123”. Any future query requesting the same user reuses that cached entry regardless of query shape.

TTL policies provide temporal consistency. User profile data might cache for hours; real-time stock prices for seconds. Effective TTL configuration balances performance with data freshness requirements for each data type in your schema.

Cache invalidation strategies determine when cached data becomes stale after mutations or external changes. Options range from simple TTL expiry to event-driven invalidation triggered by specific mutations, tag-based bulk invalidation, or subscription-based real-time updates.

The challenges of caching in GraphQL

The most significant challenge stems from GraphQL’s use of POST requests with query strings in the request body, which bypasses all standard HTTP caching mechanisms. Every identical query requires a full network round-trip unless you explicitly work around this limitation.

Query complexity adds another layer of difficulty. A single GraphQL query can traverse multiple relationships, request computed fields, and include conditional directives. Nested data structures within queries create dependencies between cached objects, where updating one object may need to invalidate multiple cache entries that reference it.

The N+1 problem is particularly painful in caching contexts. When resolving nested relationships, GraphQL servers may fire dozens of individual database queries for related objects. Caching these without proper batching leads to fragmentation — related data scattered across separate cache entries rather than efficiently grouped.

Mutations add another layer of complexity. A single mutation might affect multiple cached queries, requiring invalidation logic that understands the relationships between different parts of your data graph.

The POST request problem

“Only queries submitted with an HTTP GET operation can be cached. POST queries cannot be cached.”
— Adobe Developer Documentation
Source link

GraphQL’s reliance on POST requests fundamentally conflicts with HTTP caching standards. HTTP caches — including browser caches, proxy caches, and CDN edge nodes — only cache GET requests, because POST requests are assumed to have side effects or sensitive payloads.

Automatic Persisted Queries (APQ) are the most widely adopted solution. APQ generates a SHA-256 hash of the query string and uses that hash as a stable query identifier. The flow works like this:

Both Apollo Client and Apollo Server support APQ out of the box. Once registered, queries convert to GET requests that CDNs can cache at the edge, combining GraphQL’s flexibility with standard HTTP caching performance. Production APQ implementations should include query allowlisting to prevent schema enumeration attacks.

Handling varying query shapes

“When caching GraphQL queries, the maximum allowed size of a query is 4096 bytes.”
— Akamai TechDocs
Source link

One of GraphQL’s greatest strengths — clients requesting exactly what they need — becomes a caching liability when different queries request overlapping but not identical fields. Two queries might request the same underlying objects but with different field selections, causing cache fragmentation where similar data lives in separate entries.

Consider two queries both requesting user data: one asks for { id, name, email }, the other for { id, name, avatar }. Naive query-level caching treats these as entirely different requests, wasting the opportunity to reuse cached id and name fields already in memory.

Normalized caching solves this by decomposing query results into individual objects stored by ID. Advanced normalization can satisfy a new query entirely from existing cached data even when the query structure differs from previously cached queries, as long as the requested fields are available for those object IDs.

Schema design plays a direct role in cacheability. Consistent field names, stable argument patterns, and clear object boundaries make it much easier to implement effective caching. Avoid deeply nested structures when flatter alternatives serve the same purpose.

Object identification for effective caching

Unique object identifiers are the foundation of normalized GraphQL caching. Without consistent, globally unique IDs, caching systems cannot reliably detect when different queries request the same underlying data, leading to fragmentation and missed optimization opportunities.

Every cacheable type in your schema should expose a stable id field that is globally unique — not just unique within that type. UUIDs work well. Composite keys that encode the type name (e.g., user_abc123) also work and make debugging easier.

The Node interface pattern from the Relay specification standardizes this. Every object implements a Node interface with a globally unique id, and a top-level node(id: ID!) query retrieves any object by ID. This pattern enables generic caching logic that works across all types.

When a mutation returns an object with a known ID, the cache can automatically update all entries referencing that object, keeping the entire cache consistent without manual intervention. This only works if your IDs are stable and globally unique.

Apollo Client cache implementation

Apollo Client is the most widely used GraphQL client and ships with a sophisticated normalized cache called InMemoryCache. InMemoryCache automatically extracts objects from query results, stores them by unique ID, and shares them across all queries that reference the same object — reducing both memory usage and network requests.

For the vast majority of use cases, InMemoryCache works transparently with minimal configuration. Production applications typically add type policies for non-standard ID patterns, field policies for paginated lists, and cache update handlers for mutations.

Cache normalization and the importance of IDs

Apollo’s normalization process extracts every object with both __typename and id from query results and stores them under a composite key like "User:123". When a later query requests the same user, Apollo reads directly from that cache entry instead of making a network request. This sharing means that updating one object automatically updates every component that displays it — no extra work required.

When a query returns data, Apollo checks whether all requested fields for each referenced object are already in the normalized cache and within their TTL. If they are, Apollo returns the data immediately without touching the network. This is entirely transparent to your application code.

Objects that lack proper identification — no id field, inconsistent __typename — cannot be normalized. They are stored as embedded data within the parent query result, which means they won’t be shared or updated automatically. Every cacheable type should have a stable, globally unique id.

When an object references another, the cache stores a pointer to the target’s cache key rather than duplicating the data. Updates to the referenced object propagate immediately to all queries that include it, maintaining application-wide consistency without manual coordination.

Fetch policies: controlling cache vs network

Fetch policies are the primary mechanism for controlling how each query balances cached data against network freshness. Apollo Client offers five policies:

Apollo’s cache API also allows direct programmatic access. cache.readQuery() and cache.writeQuery() operate on complete query results; cache.readFragment() and cache.writeFragment() target individual objects using GraphQL fragments. When a query fails but cached data exists, Apollo can return the stale cache alongside error information, enabling graceful degradation under unreliable network conditions.

Customizing cache behavior with type policies

Type policies give you control over how Apollo normalizes, merges, and reads specific types. The most common use case is custom key generation for objects that don’t use a field literally named id, or that require composite keys based on multiple fields.

“`javascript const cache = new InMemoryCache({ typePolicies: { Product: { keyFields: [“sku”], // Use ‘sku’ instead of ‘id’ }, PaginatedUsers: { fields: { users: { // Merge paginated results instead of replacing merge(existing = [], incoming) { return […existing, …incoming]; }, }, }, }, }, }); “`

Merge functions control how Apollo combines incoming data with what’s already cached for the same object. The default behavior replaces cached fields with incoming values, but custom merge functions can implement array concatenation for pagination, preserve certain fields, or apply business logic during updates.

Field policies add even more granularity by customizing individual fields — implementing computed values, cache redirects that point lookups to a canonical cache location, or custom read functions that transform stored data before returning it to components.

Manual cache operations after mutations

After a mutation, you typically want the UI to reflect the new data without a full refetch. Apollo provides three main patterns for keeping the cache in sync after writes:

“`javascript // 1. cache.modify() — surgical field update cache.modify({ id: cache.identify(user), fields: { name() { return newName; }, }, });// 2. cache.writeFragment() — update a specific object cache.writeFragment({ id: `User:${userId}`, fragment: gql`fragment UpdatedUser on User { name email }`, data: { name: newName, email: newEmail }, });// 3. Optimistic response — update UI before server confirms const [updateUser] = useMutation(UPDATE_USER, { optimisticResponse: { updateUser: { __typename: “User”, id: userId, name: newName }, }, }); “`

cache.modify() is the most surgical — it updates specific fields without triggering query re-evaluation for unaffected data. cache.writeFragment() is ideal when a mutation returns the updated object and you want to apply it to all queries referencing that entity. Optimistic responses update the UI immediately and roll back automatically if the mutation fails.

Bypassing the cache

Some queries should never serve stale data: authentication checks, payment states, permissions. Use network-only fetch policy for these to ensure every execution fetches fresh data. If you also don’t want results stored (for security), use no-cache instead.

The cache-and-network policy is often the best compromise for data that changes occasionally: it displays cached content instantly while fetching an update in the background. Users see immediate content; the display updates silently when fresh data arrives.

When bypassing the cache entirely, implement appropriate loading states and error handling — there is no cached fallback if the network request fails.

Persisting the cache across sessions

Cache persistence stores Apollo’s normalized data in localStorage or IndexedDB so it survives page refreshes and browser restarts. This dramatically improves perceived load performance — the app hydrates instantly from the persisted cache while background requests fetch updates.

“`javascript import { persistCache, LocalStorageWrapper } from “apollo3-cache-persist”;const cache = new InMemoryCache();await persistCache({ cache, storage: new LocalStorageWrapper(window.localStorage), maxSize: 1048576, // 1MB limit }); “`

Storage size limits require attention — browsers typically cap localStorage at 5–10 MB. Implement size monitoring and automatic cleanup to prevent persistence failures silently breaking the cache. Version your cache keys so schema updates automatically invalidate incompatible persisted data rather than causing subtle runtime errors.

Do not persist sensitive data like authentication tokens or personal information that should not survive across sessions. Persistent storage is readable by any JavaScript running on the same origin.

Resetting the cache

Cache resets are typically triggered after user logout, account switching, or when data corruption is detected. Apollo provides three levels of clearing:

“`javascript // Full reset: clear cache and re-execute all active queries await client.resetStore();// Clear without re-fetching: useful when switching user context await client.clearStore();// Targeted eviction: remove a specific object cache.evict({ id: cache.identify(staleObject) }); cache.gc(); // Clean up now-dangling references “`

resetStore() provides the strongest consistency guarantee but re-fires every active query. clearStore() is appropriate when you want a clean slate but don’t need immediate re-population. cache.evict() followed by cache.gc() surgically removes specific entries while preserving the rest of the cache.

Server-side caching solutions

Server-side caching prevents redundant computation, database queries, and resolver execution — complementing client-side caching which eliminates redundant network requests. The two layers serve different purposes and must be designed together.

Because all GraphQL queries share a single endpoint, server-side caching must generate cache keys from query content rather than URLs — typically a hash of the normalized query plus variables plus any relevant context like user role or locale.

Response caching with Apollo Server and Envelop

Apollo Server’s @cacheControl directive lets schema designers specify caching parameters directly in the schema definition, giving fine-grained control over TTL and scope per field and type.

“`graphql type Product @cacheControl(maxAge: 3600) { id: ID! name: String! price: Float! @cacheControl(maxAge: 60) # prices change often description: String @cacheControl(maxAge: 86400) reviews: [Review!]! @cacheControl(maxAge: 300, scope: PUBLIC) }type User @cacheControl(maxAge: 0, scope: PRIVATE) { id: ID! name: String! email: String! } “`

scope: PUBLIC allows responses to be shared across users — suitable for product catalogs, blog posts, public data. scope: PRIVATE restricts caching to individual user sessions. Apollo Server uses the most restrictive maxAge and scope values from all fields included in a query to compute the final cache directive for the response.

For the Envelop plugin ecosystem (used with GraphQL Yoga and other servers), the @envelop/response-cache plugin provides TTL-based server-side caching with pluggable storage backends:

“`javascript import { useResponseCache } from “@envelop/response-cache”; import { createRedisCache } from “@envelop/response-cache-redis”;const redis = new Redis({ host: “localhost”, port: 6379 });const getEnveloped = envelop({ plugins: [ useResponseCache({ cache: createRedisCache({ redis }), ttl: 2000, // 2 seconds default TTL ttlPerType: { Product: 60_000, // 60 seconds for products User: 0, // never cache user data }, includeExtensionMetadata: true, // adds cache HIT/MISS to response }), ], }); “`

DataLoader and batch caching patterns

DataLoader addresses the N+1 problem by batching and caching database requests within a single query execution. When multiple resolvers request related data, DataLoader collects those requests and fires a single batched database query for all of them — then caches the results for the remainder of that request.

“`javascript import DataLoader from “dataloader”;// Create per-request DataLoader instances const userLoader = new DataLoader(async (userIds) => { const users = await db.users.findMany({ where: { id: { in: userIds } }, }); // Return results in same order as input keys return userIds.map((id) => users.find((u) => u.id === id) ?? null); });// In resolvers — called N times, batched into 1 query const postAuthorResolver = (post) => userLoader.load(post.authorId); “`

DataLoader cache entries are scoped to the request and cleared automatically between executions, eliminating stale data concerns while providing significant performance gains within individual queries. For frequently accessed, slow-changing data (e.g., product categories), you can prime the DataLoader cache proactively before query execution begins.

Edge caching with CDN or reverse proxy

CDN edge caching serves responses from nodes geographically close to users, cutting latency for global audiences. GraphQL’s POST requests mean standard CDN configurations won’t cache anything without additional setup. Automatic Persisted Queries (APQ) convert registered queries to GET requests that CDNs cache natively.

For Nginx or Varnish reverse proxies positioned in front of your GraphQL server, you can configure POST body-based cache key generation — though this is more operationally complex than APQ and requires custom VCL or Lua scripting.

Public data like product catalogs or CMS content can be CDN-cached with long TTL values (hours to days). User-specific or frequently mutated data should either bypass the CDN or use short TTL values with aggressive invalidation. Webhook-based cache purging triggers CDN invalidation automatically when upstream data changes, keeping edge caches fresh without excessive TTL churn.

Advanced caching patterns and best practices

Advanced caching implementations go beyond simple TTL-based response caching to handle complex data relationships, real-time requirements, and high-scale performance demands. These patterns typically emerge in production environments where basic caching approaches hit their limits in cache hit rates, consistency guarantees, or operational complexity.

Stale-while-revalidate (SWR) patterns provide excellent perceived performance by serving cached data immediately while fetching a fresh copy in the background. Users always see data instantly; the display updates silently when the background fetch completes. This pattern eliminates the latency spike of cache misses from the user’s perspective.

Optimizing cache invalidation strategies

Cache invalidation is the hardest part of GraphQL caching, and the source of most production incidents. Effective invalidation balances data freshness against cache hit rate — over-invalidating destroys performance; under-invalidating causes stale reads.

TTL-based invalidation automatically expires entries after a set duration. Simple and reliable for data with predictable update frequency — product descriptions, blog posts, configuration data. Use short TTLs (seconds to minutes) for data that changes often; longer TTLs (hours) for stable reference data.

Mutation-triggered invalidation clears specific cache entries when a related mutation succeeds. More precise than TTL — data stays fresh immediately after writes. Requires maintaining a mapping from mutation types to affected cache keys, which grows complex in large schemas.

Tag-based invalidation associates cache entries with tags representing their data dependencies (e.g., product:123, category:electronics). When product 123 changes, you purge all entries tagged product:123 in one operation. This scales well for complex applications and is supported natively by Fastly, Cloudflare, and the Envelop response cache plugin.

“`javascript // Envelop response cache with tag-based invalidation useResponseCache({ cache: createRedisCache({ redis }), idFields: [“id”], invalidateViaMutation(mutationName) { // After updateProduct mutation, purge all cached Product queries if (mutationName === “updateProduct”) return [“Product”]; if (mutationName === “deleteReview”) return [“Review”, “Product”]; return []; }, }) “`

Subscription-based invalidation pushes cache updates to clients in real-time when server data changes. Strongest consistency, highest operational complexity. Appropriate for collaborative applications where multiple users edit shared data.

Persistent and offline caching

Persistent caching extends GraphQL caching beyond individual sessions by storing data in localStorage or IndexedDB. Application startup performance improves dramatically — the app hydrates from the persisted cache in milliseconds while background requests fetch updates.

Offline support via Progressive Web App patterns combines persistent caching with service workers to handle scenarios where network access is unavailable or unreliable. The service worker intercepts GraphQL requests and serves persisted cache entries when the network is down, providing graceful degradation rather than a broken experience.

Cache hydration strategy matters for startup performance: restore critical data (user session, primary content) immediately; lazy-load secondary cached content only when the relevant UI is requested. Implement versioning and migration strategies so schema updates automatically invalidate incompatible persisted data from previous app versions.

Fragment caching for performance

GraphQL fragments are a natural caching unit for component-based architectures. When UI components define their data requirements via fragments (fragment colocation), caching systems can store fragment results independently and reuse them across different queries and components that include the same fragment.

Fragment cache keys must account for both the fragment structure and any arguments or variables that affect results. A fragment requesting paginated reviews with first: 10 produces different data than the same fragment with first: 20 — the arguments must be part of the key.

Dependency tracking between fragments enables cascade invalidation: updating a base fragment automatically invalidates dependent fragments built on top of it. Monitor fragment cache hit ratios and execution times to verify that fragment-level cache management overhead is smaller than the performance gains from improved hit rates.

Measuring cache effectiveness

Cache hit ratio is the primary metric: the percentage of requests served from cache vs those requiring a fresh fetch. Target 80%+ for most production applications. Below 60% usually indicates poor key design, over-invalidation, or TTLs that are too short for your actual update frequency.

Response time percentiles (p50, p95, p99) provide user-facing evidence of caching impact. Measure separately for cache hits and misses — the difference quantifies the actual latency benefit you’re providing. These measurements should cover different query types and traffic patterns, not just average load.

Track cache invalidation frequency and stale data incidents separately to maintain the balance between performance and correctness. Sudden spikes in invalidation frequency often indicate a bug in mutation handling or an unexpected data dependency.

Business impact metrics — user engagement, conversion rates, infrastructure costs — connect cache performance to outcomes that matter to stakeholders. A 20% improvement in p95 response time is compelling; showing it correlates with a 5% lift in conversion makes the investment undeniable.

Tools for debugging and optimizing cache performance

Apollo Client DevTools provides a cache inspector that visualizes the normalized data structure, showing exactly how objects are stored and referenced. This makes it straightforward to spot normalization failures — objects stored as embedded data instead of normalized entries, or duplicate copies of the same entity stored under different keys.

Query analysis identifies which operations benefit most from caching investment. Queries that are slow, frequently executed, and have low hit rates are the highest-ROI optimization targets. GraphQL Playground and similar tools surface query performance metrics that guide prioritization decisions.

Custom cache performance middleware in your GraphQL server allows tracking metrics per operation name, user cohort, or feature flag. This granularity reveals which application features drive the most cache load and where invalidation is causing unnecessary churn.

Performance profiling of the caching layer itself matters at scale. Complex normalization, expensive cache key generation, or inefficient lookup algorithms can negate the gains from caching. Profile regularly to ensure your caching implementation is net-positive for overall latency.

Comparing GraphQL caching libraries

The GraphQL client ecosystem offers distinct caching approaches with real trade-offs. Apollo Client remains the most feature-complete option with normalized caching, extensive tooling, and the largest community, but carries a larger bundle and a steeper learning curve than alternatives.

urql’s modular architecture allows applications to start with simple document caching and upgrade to full normalization via the Graphcache exchange only when complexity justifies it. The Graphcache exchange provides normalized caching approaching Apollo’s sophistication at a fraction of the bundle cost.

Relay takes the most opinionated approach — its compiler analyzes your queries at build time to generate optimal data-fetching and caching code. Performance is exceptional, but adopting Relay means committing to its entire workflow including the compiler, fragment conventions, and connection specification. It is less suitable for incremental adoption.

Library selection should weigh caching capability, team familiarity, bundle size budget, and long-term maintenance trajectory. For most new projects, Apollo Client’s ecosystem breadth makes it the lowest-risk choice. For bundle-sensitive applications, urql with Graphcache is a well-maintained, growing alternative.

Apollo Client vs Relay vs urql: when to use each

Choose Apollo Client when you need the full feature set: normalized caching with extensive customization, React and non-React framework support, a large plugin ecosystem, and the best available DevTools for debugging cache state.

Choose urql when bundle size matters, your team prefers simpler APIs, or you want the flexibility to swap caching strategies per environment. Graphcache’s offline mutation queue and schema-aware optimistic updates give it capabilities that close much of the gap with Apollo at a fraction of the weight.

Choose Relay when you’re building a large-scale React application where static query analysis, automatic pagination support, and compile-time optimization outweigh the investment in learning Relay’s conventions and toolchain.

Development experience varies substantially. Apollo provides the most comprehensive DevTools and documentation. urql offers the simplest API surface. Relay provides excellent performance guarantees but requires deep investment in its compiler and conventions before productivity kicks in.

Future-proofing your GraphQL cache

The GraphQL caching landscape is evolving quickly with emerging patterns that address current limitations. Real-time cache synchronization via GraphQL subscriptions is one pattern gaining traction: rather than polling or relying on TTL, cache updates are pushed to clients the moment server data changes.

Edge computing platforms like Cloudflare Workers and Fastly Compute are beginning to support full GraphQL execution at the edge, not just caching of pre-computed responses. This combines CDN latency benefits with the full flexibility of GraphQL execution, enabling dynamic queries to be resolved in milliseconds globally.

Incremental delivery via @defer and @stream directives (now in the GraphQL specification) allows responses to arrive in multiple parts, enabling different cache TTLs per deferred chunk. Critical above-the-fold data can be cached aggressively; slower or lower-priority fields can be fetched fresh with each request.

Future GraphQL specification versions are being discussed with native cache hint and invalidation directives, which would reduce the current fragmentation across library-specific implementations and improve interoperability between GraphQL tools and infrastructure.