Persisted Queries, Trusted Documents and HTTP Caching — GraphQL in Production

Automatic Persisted Queries (APQ) send a SHA-256 hash of the document instead of the full text; the server caches the mapping on first use. That shrinks requests and enables GET requests (/graphql?extensions=…&variables=…) that CDNs can cache. Trusted documents (persisted operations registered at build time) go further: the server only executes known operations — a strong security and performance guarantee for first-party clients. Combine with Cache-Control hints per field/type to compute response cacheability.

Persisted query options

Criterion	Ad-hoc queries	APQ	Trusted documents
Request size	Full document	Hash (after first)	Hash/ID
CDN cacheable	Rarely	Yes (GET)	Yes (GET)
Blocks arbitrary queries	No	No	Yes
Suits	Public explorers	Public APIs	First-party web/mobile

# APQ request (GET, cacheable by CDN)
GET /graphql?operationName=ProductPage&variables={"id":"prd_1"}&extensions={"persistedQuery":{"version":1,"sha256Hash":"ecf4edb46db40b5132295c0291d62fb65d6759a9eedfa4d5d612dd5ec54a6b38"}}

# Trusted documents: build step extracts operations → manifest uploaded to the server
# client sends only {"documentId": "sha256:ecf4…", "variables": {...}}
# server rejects anything not in the manifest

Common pitfalls

APQ treated as a security control (any query can still be registered).
Caching responses that contain per-user data at the CDN.
Not versioning the trusted-document manifest with app releases.

Key points

APQ: smaller, GET-cacheable
Trusted documents: allowlist
Cache hints drive Cache-Control

Further reading: Apollo: Automatic persisted queries

Practice questions

What's the difference between APQ and trusted documents?

Answer

APQ is a performance optimization (any query can be registered on the fly); trusted documents are an allowlist registered at build time, so the server refuses unknown operations.

How do persisted queries enable CDN caching?

Answer

Short hashed requests can be sent as GET with the hash and variables in the URL, so CDNs can key and cache responses like any GET request.