Course contentsShow
← Software Engineering
Lesson 821 of 1,93325. RPC and GraphQL API DesignFree lesson

Persisted Queries and Query Whitelisting

Pre-registering queries to improve performance, security, and prevent arbitrary query execution.

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:

  1. Security risk: Malicious clients can craft expensive queries that overwhelm your server
  2. 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.