Query body sent once. Hash sent forever.

APQ stores queries on first use and caches the hash-to-query mapping. Every subsequent request sends only the hash, enabling CDN edge caching via GET requests—with no CI/CD setup required.

The problem

GraphQL sends too much data, too often

Every request carries the full operation. CDN caching is blocked by default. Registration is too costly to set up manually.

Full query bodies repeat on every request

Clients resend the complete operation text with each call. Complex queries run several kilobytes per request, repeated across every client, every page load, every background fetch.

POST requests cannot use CDN edge caching

GraphQL uses POST by default. CDNs do not cache POST responses, so even read-only queries hit your origin on every call.

Traditional persisted queries require upfront registration

Pre-registering operations means modifying CI/CD, maintaining manifest files, and coordinating deploys. The overhead discourages teams from adopting the pattern.

Our solution

Register automatically, cache at the edge

APQ removes the upfront registration step. Queries are cached the first time a client sends them. After that, clients send only the SHA-256 hash—making GET-based CDN caching possible for any query.

How APQ works end to end

1. The client sends the full query body alongside its SHA-256 hash in the extensions.persistedQuery parameter.
2. The router receives the request, finds no cached entry for this hash, stores the query-to-hash mapping, and executes the operation.
3. On subsequent requests, the client sends only the hash—no query body. The router retrieves the stored operation and executes it.
4. GET requests with only the hash parameter are CDN-cacheable. CDN edge nodes serve cached responses without forwarding to origin.
5. If the hash is not found (first request, or a router instance that has not cached it yet), the router does not recognize it and the request fails. The client resends with the full body to register it.
6. Storage is in-memory by default. Redis provides persistence across router restarts and sharing across multiple router instances.

No CI/CD changes. No manifest files. Zero-friction adoption.

Before & After

Storage

In-memory or Redis

In-memory

Simple. Configurable size (default 100 MB) and TTL. Does not survive router restarts. Best for single-instance deployments.

Redis

Persists across restarts. Shared across multiple router instances. Set storage.provider_id and define a Redis provider in storage_providers.redis.

How APQ works in Cosmo Router

01 Body + hash on first call.

First request

The client sends the query body and its SHA-256 hash in the extensions.persistedQuery parameter. The router stores the hash-to-query mapping and executes the operation.

02 In-memory or Redis.

Router caches

The hash-to-query mapping is stored in the configured cache: in-memory with a configurable size and TTL, or Redis for persistence across router restarts.

03 Hash only. Smaller payload.

Subsequent requests

The client sends only the hash—no query body. The router retrieves the stored operation and executes it. GET requests are supported, enabling CDN caching.

04 Edge cache. Origin traffic down.

CDN serves

GET requests with the hash are cached at CDN edge locations. Repeat queries for the same operation are served without reaching origin.

Capabilities

Cache, CDN, and compatibility

In-memory or Redis. GET-compatible. Works with Apollo Client out of the box.

In-memory cache

Configurable cache size and TTL. Simple to enable with a single automatic_persisted_queries.enabled: true flag. Suitable for single-instance deployments.

Redis storage

Persist query mappings across router restarts and share them across multiple router instances. Set storage.provider_id to point at your Redis connection.

GET request support

Clients that send only the hash can use GET requests. CDNs cache GET responses by URL, so frequently used queries are served from the edge.

Apollo-compatible protocol

APQ follows the Apollo persistedQuery protocol. Apollo Client and any other client that implements the same protocol work without custom configuration.

Enable CDN caching for your GraphQL queries

Set automatic_persisted_queries.enabled: true in your router config. No other changes required.

FAQ

APQ on Cosmo Router

How does APQ differ from Persisted Operations?

What happens if the router does not have the cached query?

What clients support APQ?

How do I enable Redis storage?

Does APQ work with GET requests?

Can APQ coexist with Persisted Operations?

Full details in the APQ documentation.