Smaller requests
Reduce request overhead for operations sent frequently over constrained networks.
GraphQL · Const
persisted queries
Persisted queries let clients send a query hash instead of the full GraphQL document. The server retrieves the stored document before validating and executing it, reducing request size.
How it works
Persisted queries, also called persisted documents, let a client identify a previously stored GraphQL operation with a hash or other short identifier. The server retrieves the full document from a store, then validates and executes it; sending the identifier also reduces request size.
Syntax
{ "id": "<query-hash>" }Key points
- The documentation groups persisted queries into trusted documents and automatic persisted queries.
- A client can transmit a query hash rather than the complete operation text.
- The server resolves the identifier through storage to recover the complete document.
- Lookup occurs before the usual validation and execution stages.
- Hash-based requests avoid sending the operation source as plaintext.
- The smaller request payload can reduce network transfer overhead.
Common mistakes
- Trusted documents are unsuitable for public APIs when arbitrary third-party clients can submit operations that were not previously approved.
Example: Send a persisted document identifier
const query = `query GetUser { user { id name } }`;
const id = await sha256(query);
await fetch("/graphql", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ id })
});The client sends a hash instead of the full operation; the server resolves that identifier to the stored document before validation and execution.
When to use it
GET and CDN caching
Cache read-only GraphQL operations through HTTP infrastructure.
Allowlisted trusted documents
Restrict execution to approved operations in a controlled client ecosystem.
Interview questions
QWhat is a persisted query?
A persisted query replaces the full GraphQL document in a request with a hash or short identifier. The server uses that value to retrieve the stored document before validation and execution.
Follow-up: How can this improve security? With trusted documents, the server can allowlist only identifiers for developer-approved operations and reject unknown ones.
QWhat does the server do with the identifier?
The server needs a store that maps the received hash or identifier to the complete GraphQL document. After lookup, normal validation and execution proceed against that document.
Follow-up: What happens on a lookup miss? The server must reject the request or use an agreed registration flow; it cannot validate or execute a document it does not have.
QWhat performance benefit do persisted queries provide?
Sending a hash instead of plaintext query text reduces the amount of data transmitted in the request. Persisted documents can also pair well with GET requests, HTTP caching, and CDNs for query operations.
Follow-up: Why does GET matter here? Query operations are safe to retrieve, so GET can participate in HTTP caching while mutations remain POST-only.
Related
trusted documentsautomatic persisted queriespersisted documentsGET requests for queriesHTTP cachingCDN usage