Persisted Queries and Query Whitelisting
What you'll learn: How pre-registering GraphQL queries improves performance, security, and control over API usage.
The Problem with Open Query Execution
In standard GraphQL deployments, clients can send any query they want to your server. While this flexibility is powerful, it creates two major issues:
- Security risk: Malicious clients can craft expensive queries that overwhelm your server
- Performance overhead: The server must parse and validate every query text on every request
What Are Persisted Queries?
Persisted queries let you pre-register approved queries on the server and reference them by ID rather than sending the full query text.
How It Works
Instead of sending the entire query string, clients send a hash or identifier:
# Client sends just:
{ "id": "abc123" }
# Instead of:
{
query: "query GetUser($id: ID!) { user(id: $id) { name email } }"
}
The server looks up query abc123 in its registry and executes the stored query.
Query Whitelisting
Taking persisted queries further, query whitelisting means the server only accepts pre-registered queries—rejecting any arbitrary query text. This is like having a bouncer who only lets people on the guest list into your API.
Benefits
- Performance: Query parsing happens once during registration, not on every request
- Security: Prevents malicious queries (like those causing N+1 problems or hitting complexity limits)
- Bandwidth: Smaller payloads—just IDs instead of full query strings
- Observability: You know exactly which queries are being used in production
Trade-offs
You lose GraphQL's dynamic querying flexibility. Clients must coordinate with your deployment pipeline to register new queries before using them.
Key Takeaway: Persisted queries and whitelisting trade GraphQL's flexibility for improved performance, security, and predictability—ideal for production environments where you control both client and server.