How does APQ differ from Persisted Operations?

Persisted Operations require upfront registration in CI/CD before clients can use them. APQ registers queries automatically on first use—no CI/CD changes needed. APQ trades the strict allowlist guarantee of Persisted Operations for zero-friction adoption.

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

The router does not recognize the hash and the request fails. The client resends the request with the full query body alongside the hash to register it. This is the standard APQ protocol: body plus hash on the first request, hash only afterward. Apollo Client supports it out of the box.

What clients support APQ?

Apollo Client has built-in APQ support. Any client that follows the Apollo APQ protocol—sending the SHA-256 hash in the `extensions.persistedQuery` parameter—works without modification.

How do I enable Redis storage?

Add a `storage_providers.redis` block with a Redis URL and set `automatic_persisted_queries.storage.provider_id` to the configured ID. The router uses Redis as the backing store instead of in-memory cache.

Does APQ work with GET requests?

Yes. When a client sends only the hash, it can use a GET request. The router resolves the stored query and executes it. CDNs cache GET responses, so repeat queries are served from the edge.

Can APQ coexist with Persisted Operations?

Yes, with one exception. APQ can run alongside Persisted Operations, but safelist mode cannot be used with APQ—the two do opposite things. Pair APQ with log-only or full-blocking Persisted Operations instead.

Automatic Persisted Queries (APQ) for GraphQL | Cosmo by WunderGraph

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

The client sends the full query body alongside its SHA-256 hash in the `extensions.persistedQuery` parameter.
The router receives the request, finds no cached entry for this hash, stores the query-to-hash mapping, and executes the operation.
On subsequent requests, the client sends only the hash—no query body. The router retrieves the stored operation and executes it.
GET requests with only the hash parameter are CDN-cacheable. CDN edge nodes serve cached responses without forwarding to origin.
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.
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.

APQ

Before & After

Before Cosmo	With Cosmo APQ
Full query body sent with every request	Query body sent once; hash sent on all subsequent requests
POST requests not cacheable at CDN edge	GET requests enable CDN edge caching
Manual operation registration required	Automatic persistence on first use—no CI/CD changes
No cross-client query reuse	Any client can execute a query using its hash after it is cached

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.

Start Free Read the Docs

Query body sent once. Hash sent forever.