Distributed caching for the Apollo Router
Redis-backed caching for query plans and APQ
This feature is only available with a GraphOS Enterprise plan. If your organization doesn't currently have an Enterprise plan, you can test this functionality by signing up for a free Enterprise trial.
If you have multiple Apollo Router instances, those instances can share a Redis-backed cache for their query plans and automatic persisted queries (APQ). This means that if any of your router instances caches a particular value, all of your instances can look up that value to significantly improve responsiveness. For more details on query plans and APQ, see the article on in-memory caching.
Prerequisites
To use this feature:
- You must have a Redis cluster (or single instance) that your router instances can communicate with.
- You must have a GraphOS Enterprise plan and connect your router to GraphOS.
How it works
Whenever a router instance requires a query plan or APQ query string to resolve a client operation:
- The router instance checks its own in-memory cache for the required value and uses it if found.
- If not found, the router instance then checks the distributed Redis cache for the required value and uses it if found. It also then replicates the found value in its own in-memory cache.
- If not found, the router instance generates the required query plan or requests the full operation string from the client for APQ.
- The router instance stores the obtained value in both the distributed cache and its in-memory cache.
Redis URL configuration
The distributed caching configuration must contain one or more URLs using different schemes depending on the expected deployment:
redis
- TCP connected to a centralized server.rediss
- TLS connected to a centralized server.redis-cluster
- TCP connected to a cluster.rediss-cluster
- TLS connected to a cluster.redis-sentinel
- TCP connected to a centralized server behind a sentinel layer.rediss-sentinel
- TLS connected to a centralized server behind a sentinel layer.
The URLs must have the following format:
One node
redis|rediss :// [[username:]password@] host [:port][/database]
Example: redis://localhost:6379
Clustered
redis|rediss[-cluster] :// [[username:]password@] host [:port][?[node=host1:port1][&node=host2:port2][&node=hostN:portN]]
or, if configured with multiple URLs:
["redis|rediss[-cluster] :// [[username:]password@] host [:port]","redis|rediss[-cluster] :// [[username:]password@] host1 [:port1]","redis|rediss[-cluster] :// [[username:]password@] host2 [:port2]"]
Sentinel
redis|rediss[-sentinel] :// [[username1:]password1@] host [:port][/database][?[node=host1:port1][&node=host2:port2][&node=hostN:portN][&sentinelServiceName=myservice][&sentinelUsername=username2][&sentinelPassword=password2]]
or, if configured with multiple URLs:
["redis|rediss[-sentinel] :// [[username:]password@] host [:port][/database][?[&sentinelServiceName=myservice][&sentinelUsername=username2][&sentinelPassword=password2]]","redis|rediss[-sentinel] :// [[username1:]password1@] host [:port][/database][?[&sentinelServiceName=myservice][&sentinelUsername=username2][&sentinelPassword=password2]]"]
Router configuration
💡 TIP
In your router's YAML config file, you should specify your Redis URLs via environment variables and variable expansion. This prevents your Redis URLs from being committed to version control, which is especially dangerous if they include authentication information like a username and/or password.
Distributed query plan caching
To enable distributed caching of query plans, add the following to your router's YAML config file:
supergraph:query_planning:experimental_cache:redis:urls: ["redis://..."]timeout: 5ms # Optional, by default: 2msttl: 24h # Optional, by default no expiration
The value of urls
is a list of URLs for all Redis instances in your cluster.
All query plan cache entries will be prefixed with plan.
within the distributed cache.
Distributed APQ caching
To enable distributed caching of automatic persisted queries (APQ), add the following to your router's YAML config file:
apq:router:cache:redis:urls: ["redis://..."]timeout: 5ms # Optional, by default: 2msttl: 24h # Optional, by default no expiration
The value of urls
is a list of URLs for all Redis instances in your cluster.
All APQ cache entries will be prefixed with apq
followed by a null byte character (referenced by the escape sequence \0
in most programming languages) within the distributed cache.