English for GraphQL Persisted Queries

Persisted queries are a GraphQL optimisation technique that replaces full query strings in requests with short identifiers, reducing payload size and enabling better security and caching. If you work with GraphQL and communicate in English about performance, security, or API design, knowing the vocabulary of persisted queries will help you participate effectively in these conversations.

Key Vocabulary

Persisted query A persisted query is a GraphQL query that has been stored on the server ahead of time and can be referenced by a unique identifier rather than sending the full query text with each request. The client sends only the query ID, not the query string. Example: “We implemented persisted queries to reduce the size of our GraphQL requests from several kilobytes to a few dozen bytes.”

Query allowlist A query allowlist (sometimes called a query safelist or approved query list) is a security measure that restricts the server to accepting only pre-approved persisted queries. This prevents clients from sending arbitrary queries, significantly reducing the attack surface. Example: “With the query allowlist in place, any query that hasn’t been registered in advance will be rejected — this protects us against introspection attacks and data exfiltration.”

Automatic persisted queries (APQ) Automatic persisted queries (APQ) is a protocol where the client first tries to send a query by its hash. If the server doesn’t recognise the hash, it responds with an error, and the client resends the full query. The server then caches it for future requests. Example: “We use Apollo’s automatic persisted queries feature — on the first request, the full query is sent and cached. On subsequent requests, only the hash is sent.”

Query hashing Query hashing is the process of generating a cryptographic hash (typically SHA-256) of a query string to produce a stable, fixed-length identifier. The hash is deterministic — the same query always produces the same hash. Example: “We hash our queries at build time using SHA-256 and register them with the server as part of the deployment process.”

CDN caching One of the benefits of persisted queries is that GET requests (with query IDs as URL parameters) can be cached at the CDN level, since the query is identified by a stable hash in the URL rather than a variable request body. Example: “Switching to persisted queries allowed us to cache our most common queries at the CDN level, which reduced origin load by 60%.”

Common Scenarios Where This Language Is Used

In a performance optimisation discussion: “Our GraphQL requests are large because we’re sending full query strings. If we implement persisted queries, we can replace those strings with short hashes and enable CDN caching for read-heavy queries. I estimate this could reduce our API payload size by 80%.”

In a security review: “One concern with our public GraphQL API is that clients can send arbitrary queries, including deep introspection queries that could expose our schema structure. Implementing a query allowlist would restrict the API to accepting only the queries our frontend actually needs.”

In a code review: “I see we’re using automatic persisted queries here. Could you make sure the query hash is generated at build time rather than at runtime? That way, we can register all queries as part of the CI pipeline and catch any unregistered queries before they reach production.”

Useful Phrases for Persisted Query Discussions

• “Persisted queries reduce the request payload significantly — instead of a full query string, we send only the hash.”
• “The query allowlist ensures that only our pre-approved queries can be executed against the API.”
• “We register new queries as part of the build process, so the server always has the latest versions.”
• “APQ works transparently — the client handles the fallback automatically if the server doesn’t recognise the hash.”
• “With persisted queries, we can use GET requests instead of POST, which enables CDN caching.”
• “The hash is computed from the normalised query string, so whitespace and comment differences don’t affect it.”
• “If a query is modified, a new hash is generated and the old one becomes invalid.”
• “We use this Apollo plugin to generate the persisted query manifest at build time.”
• “The server checks the incoming hash against the registered query store and returns an error for unknown queries.”
• “Persisted queries are particularly valuable for mobile clients where bandwidth is limited.”

Comparing Persisted Query Strategies

There are two main approaches to persisted queries, and knowing how to compare them in English will help you in design discussions:

Pre-registered (compile-time): Queries are hashed and registered with the server during the build process. This provides the strongest security — no unregistered queries can ever reach the server — but requires a coordinated deployment.

Automatic persisted queries (runtime): Queries are cached on first use. This is simpler to implement and requires no coordination between deployments, but does not provide the security benefit of a strict allowlist.

Use this framing: “Pre-registered persisted queries offer better security but require tighter coordination between the client and server deployments. APQ is more flexible and easier to adopt incrementally, but doesn’t give us allowlist enforcement.”

Practice Suggestion

Write a brief technical proposal (200-250 words) in English recommending the adoption of persisted queries for a fictional GraphQL API used by a mobile application. Explain the problem you are solving, your proposed approach (pre-registered or APQ), the expected benefits, and any trade-offs or migration steps. Use at least four terms from this post and focus on making the proposal persuasive and concrete.