Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL Federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Docs
Start for Free

Distributed Caching for the Apollo Router

Configure Redis-backed caching for query plans and APQ


This feature is only available with a GraphOS Enterprise plan.
You can test it out by signing up for a free Enterprise trial.

If you have multiple Apollo instances, those instances can share a Redis-backed cache for their and (). This means that if any of your 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:

How it works

Whenever a router instance requires a or APQ query string to resolve a client :

  1. The router instance checks its own in-memory cache for the required value and uses it if found.
  2. 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.
  3. If not found, the router instance generates the required query plan or requests the full operation string from the client for APQ.
  4. The router instance stores the obtained value in both the distributed cache and its in-memory cache.

Redis URL configuration

The 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:

router.yaml
supergraph:
query_planning:
cache:
redis:
urls: ["redis://..."]

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:

router.yaml
apq:
router:
cache:
redis:
urls: ["redis://..."]

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.

Common Redis configuration

Redis configuration is done in the same way for APQ caching, query plan caching and entity caching.

router.yaml
supergraph:
query_planning:
cache:
redis:
urls: ["redis://..."]
username: admin/123 # Optional, can be part of the urls directly, mainly useful if you have special character like '/' in your password that doesn't work in url. This field takes precedence over the username in the URL
password: admin # Optional, can be part of the urls directly, mainly useful if you have special character like '/' in your password that doesn't work in url. This field takes precedence over the password in the URL
timeout: 5ms # Optional, by default: 2ms
ttl: 24h # Optional
namespace: "prefix" # Optional
#tls:
required_to_start: false # Optional, defaults to false
reset_ttl: true # Optional, defaults to true

Timeout

Connecting and sending commands to Redis are subject to a timeout, set by default to 2ms, that can be overriden.

TTL

The ttl option defines the default global expiration for Redis entries. For APQ caching, the default is no expiration, while for query plan caching, the default expiration is set to 30 days.

Namespace

When using the same Redis instance for multiple puposes, the namespace option defines a prefix for all the keys defined by the router.

TLS

For Redis TLS connections, you can set up a client certificate or override the root certificate authority by configuring tls in your router's YAML config file. For example:

apq:
router:
cache:
redis:
urls: [ "rediss://redis.example.com:6379" ]
tls:
certificate_authorities: ${file./path/to/ca.crt}
client_authentication:
certificate_chain: ${file./path/to/certificate_chain.pem}
key: ${file./path/to/key.pem}

Required to start

When active, the required_to_start option will prevent the Router from starting if it cannot connect to Redis. By default, the Router will still start without a connection to Redis, which would result in only using the in-memory cache for APQ and query planning, and sending the requests to undisturbed.

Reset TTL

When this option is active, accessing a cache entry in Redis will reset its expiration.

Previous
In-Memory Caching
Next
Entity Caching
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc., d/b/a Apollo GraphQL.

Privacy Policy

Company