Automatic Persisted Queries (APQ)

Automatic Persisted Queries (APQ) enable GraphQL clients to send a server the hash of their query string, instead of sending the query string itself. When query strings are very large, this can significantly reduce network usage.

The router supports using APQ in its communications with both clients and subgraphs:

• In its communications with clients, the router acts as a GraphQL server, because it receives queries from clients.

• In its communications with subgraphs, the router acts as a GraphQL client, because it sends queries to subgraphs.

Because the router's role differs between these two interactions, you configure these APQ settings separately.

In-memory caching

The router uses an in-memory LRU cache to store automatic persisted queries. You can configure certain caching behaviors for APQ.

APQ with clients

The router enables APQ caching for client operations by default. In your router's YAML config file, you can configure the maximum number of APQ entries in the cache like so:

1apq:
2  router:
3    cache:
4      in_memory:
5        limit: 512 # This is the default value.

You can also disable client APQ support entirely like so:

1apq:
2  enabled: false

APQ with subgraphs

By default, the router does not use APQ when sending queries to its subgraphs.

In your router's YAML config file, you can configure this APQ support with a combination of global and per-subgraph settings:

1apq:
2  subgraph:
3    # Disables subgraph APQ globally except where overridden per-subgraph
4    all:
5      enabled: false
6    # Override global APQ setting for individual subgraphs
7    subgraphs:
8      products:
9        enabled: true

In the example above, subgraph APQ is disabled except for the products subgraph.

Distributed caching with Redis

If you have multiple GraphOS Router instances, those instances can share a Redis-backed cache for their automatic persisted queries (APQ). This means that if any of your router instances caches a particular APQ query string, all of your instances can look up that value to significantly improve responsiveness.

Prerequisites

To use distributed caching:

• 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 an APQ query string to resolve a client operation:

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

1redis|rediss :// [[username:]password@] host [:port][/database]

Example: redis://localhost:6379

Clustered

1redis|rediss[-cluster] :// [[username:]password@] host [:port][?[node=host1:port1][&node=host2:port2][&node=hostN:portN]]

or, if configured with multiple URLs:

1[
2  "redis|rediss[-cluster] :// [[username:]password@] host [:port]",
3  "redis|rediss[-cluster] :// [[username:]password@] host1 [:port1]",
4  "redis|rediss[-cluster] :// [[username:]password@] host2 [:port2]"
5]

Sentinel

1redis|rediss[-sentinel] :// [[username1:]password1@] host [:port][/database][?[node=host1:port1][&node=host2:port2][&node=hostN:portN]
2                            [&sentinelServiceName=myservice][&sentinelUsername=username2][&sentinelPassword=password2]]

or, if configured with multiple URLs:

1[
2  "redis|rediss[-sentinel] :// [[username:]password@] host [:port][/database][?[&sentinelServiceName=myservice][&sentinelUsername=username2][&sentinelPassword=password2]]",
3  "redis|rediss[-sentinel] :// [[username1:]password1@] host [:port][/database][?[&sentinelServiceName=myservice][&sentinelUsername=username2][&sentinelPassword=password2]]"
4]

Router configuration

To enable distributed caching of automatic persisted queries (APQ), add the following to your router's YAML config file:

1apq:
2  router:
3    cache:
4      redis:
5        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.

Redis configuration options

1apq:
2  router:
3    cache:
4      redis:
5        urls: ["redis://..."]
6        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
7        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
8        timeout: 2s # Optional, by default: 500ms
9        ttl: 24h # Optional, default is no expiration
10        namespace: "prefix" # Optional
11        #tls:
12        required_to_start: false # Optional, defaults to false
13        reset_ttl: true # Optional, defaults to true
14        pool_size: 4 # Optional, defaults to 1

Timeout

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

TTL

The ttl option defines the default global expiration for Redis entries. For APQ caching, the default is no expiration.

Namespace

When using the same Redis instance for multiple purposes, 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:

1apq:
2  router:
3    cache:
4      redis:
5        urls: ["rediss://redis.example.com:6379"]
6        tls:
7          certificate_authorities: ${file./path/to/ca.crt}
8          client_authentication:
9            certificate_chain: ${file./path/to/certificate_chain.pem}
10            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.

Reset TTL

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

Pool size

The pool_size option defines the number of connections to Redis that the router will open. By default, the router will open a single connection to Redis. If there is a lot of traffic between router and Redis and/or there is some latency in those requests, it is recommended to increase the pool size to reduce that latency.