What are GraphQL persisted queries and how do they work?
A persisted query is a GraphQL operation that the server already knows before any client sends it. Instead of putting the full query text in each request, the client sends an identifier. The server uses that identifier to fetch the stored document and then runs it as usual.
The identifier is usually a SHA-256 hash of the operation document. The document is normalized first, which means applying consistent whitespace, comment stripping and formatting rules. Without normalization, two copies of the same query that differ only in indentation would produce different hashes. Every party that computes the ID must apply the same rules.
A request carries the ID, the variables and the operation name, but no query text. For example: {"id": "9f2c…e41a", "operationName": "GetOrder", "variables": {"orderId": "123"}}. The field names depend on the client and server. Some implementations place the hash under an extensions key.
The request path looks like this:
client ──(id + variables)──▶ hash lookup in store ──(document)──▶ parse ▶ validate ▶ execute ──▶ response
The lookup happens before parsing. This order matters for three reasons:
- Smaller requests. Large operations no longer travel over the wire on every call.
- Work is done once. Parsing and validation can run once per document and be cached under the hash, instead of running on every request.
- Control over what runs. If only stored documents execute, the server never parses arbitrary client-supplied text. An unknown ID fails at the lookup step, which costs one key lookup and no parse.
Whether you actually get that third benefit depends on how documents enter the store. The next section covers this.
import { createHash } from "node:crypto";
import { parse, print, validate, execute, DocumentNode, GraphQLSchema } from "graphql";
// Normalize, then hash. print(parse()) yields canonical whitespace and drops comments,
// so formatting-only differences produce the same ID. Client tooling must apply the same rules.
export function normalize(source: string): string {
return print(parse(source));
}
export function persistedId(source: string): string {
return createHash("sha256").update(normalize(source)).digest("hex");
}
const store = new Map<string, string>(); // id -> normalized document text
const cache = new Map<string, DocumentNode>(); // id -> parsed and validated AST
// Populated ahead of time, e.g. from a build step. Nothing is added at request time.
export function register(source: string): void {
store.set(persistedId(source), normalize(source));
}
interface PersistedRequest { id: string; operationName?: string; variables?: Record<string, unknown>; }
export async function handle(schema: GraphQLSchema, req: PersistedRequest) {
// The lookup runs before any parsing. An unknown ID costs one map lookup and no parse.
const text = store.get(req.id);
if (text === undefined) {
return { errors: [{ message: "PersistedQueryNotFound" }] };
}
// Parse and validate once per document, then reuse the cached AST.
let document = cache.get(req.id);
if (!document) {
document = parse(text);
const errors = validate(schema, document);
if (errors.length > 0) return { errors };
cache.set(req.id, document);
}
return execute({ schema, document, operationName: req.operationName, variableValues: req.variables });
}
A minimal graphql-js handler that normalizes and hashes documents ahead of time, then resolves each request's ID from a store before parsing, validating and executing, and caches the parsed AST under the hash.
Why doesn't APQ block arbitrary queries?
With automatic persisted queries (APQ), documents enter the store at runtime, from the client. The client hashes its query, usually with SHA-256, and sends only the hash. If the server has never seen that hash, it returns a "persisted query not found" error. The client then retries with the full query text and the hash. The server checks that the hash matches the text, stores the pair, and executes the query. Every later request for that hash skips the full text.
Look at what that retry means. Any client, including someone with curl and your endpoint URL, can send a new query, take the miss, resend the full text, and get it executed and cached. The server never rejects a document because it is unfamiliar. It only learns it. Deeply nested queries, expensive field combinations and introspection all pass through unchanged.
APQ exists to shrink request payloads and to make GET requests short enough for CDNs and HTTP caches to key on. Those benefits are real, but it is a transport optimization. A common mistake is to see hashes in the request logs and assume only known operations are running. Unless the server refuses raw query text, nothing is enforced.
| APQ | Build-time query allowlist | |
|---|---|---|
| Who registers operations | Any client, at runtime | Your CI pipeline, from source |
| Unknown ID | Client retries with full text and it gets registered | Request rejected |
| Raw query text accepted | Yes | No, when enforcement is on |
| Main benefit | Smaller requests, GET caching | Only reviewed operations can run |
Who should use a query allowlist, and when should you avoid it?
A query allowlist fits best when you own every client that talks to the API. If your GraphQL endpoint serves your own web app and your own iOS and Android builds, every legitimate operation already exists in source control. Extracting those operations at build time costs little, and the server can then reject everything else. Mobile benefits most because old app versions stay installed for a long time. The allowlist keeps every operation those builds ever shipped, so they keep working.
Adopt enforcement when the endpoint is reachable from the public internet and you have seen, or expect, scraping, deeply nested queries, or schema probing. Without an allowlist, anyone can send any query your schema permits. With one, an attacker can only replay operations your own clients already send.
When to avoid it
- Public APIs for third-party developers. You cannot know their queries in advance, and the ability to write arbitrary queries is the reason they use the API.
- Early-stage products. When clients change daily, a missing manifest entry becomes a frequent cause of broken deploys.
- Teams without reliable CI. If manifest publishing is manual or flaky, a client will eventually ship an operation the server has never seen.
What it does not cover
An allowlist checks the query document, not its inputs. An approved operation with first: 100000 is still expensive, so you still need limits on pagination arguments and on query cost. An allowlist also does nothing for authorization. If a resolver returns another user's data, the approved query will return it too.
How do you build a persisted query manifest pipeline in CI?
The pipeline has four steps: extract, normalize, hash, publish. Each step exists so the client and the server agree, byte for byte, on what a query is.
Extract and normalize
At build time, collect every operation from the client source. Do not capture queries at runtime. Static extraction gives you a complete, reviewable list before anything ships. Then normalize each document the same way every time:
- Inline every fragment the operation references, transitively.
- Sort fragment definitions by name.
- Strip comments.
- Print the result with one deterministic printer.
Two developers who format the same query differently should produce identical output.
Hash and generate the manifest
Hash the normalized string, typically with SHA-256 over UTF-8 bytes, and use the hex digest as the operation ID. The manifest is a JSON object mapping each ID to its full document, for example {"<sha256>": "query GetUser($id: ID!) { user(id: $id) { id name } }"}. Commit it as a build artifact tied to the client version.
Publish before shipping
Upload the manifest to the server or registry, and confirm the upload succeeded, before the client build is released. Publishing is additive. Never remove IDs that older clients still send.
Catch hash mismatches in CI
The most common failure is a hash mismatch. The client hashes its document one way, and the server or registry re-hashes it after its own normalization. Every request is then rejected as unknown. Typical causes are a different printer, different fragment ordering, or trailing whitespace.
Test for this in CI:
- Take the generated manifest.
- Run each document through the server's normalization and hashing code.
- Fail the build if any recomputed ID differs from its key.
// check-manifest.ts: CI gate that recomputes every manifest ID with the server's normalizer.
// Usage: npx tsx check-manifest.ts persisted-queries.json
import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";
import { parse, print, visit, Kind, DefinitionNode, FragmentDefinitionNode } from "graphql";
// Shared normalizer. The client build and the server import this same function,
// so both sides hash identical bytes.
export function normalize(source: string): string {
const doc = parse(source); // the parser drops comments and insignificant whitespace
const ops = doc.definitions.filter((d) => d.kind === Kind.OPERATION_DEFINITION);
if (ops.length !== 1) throw new Error("expected exactly one operation per document");
const frags = new Map<string, FragmentDefinitionNode>();
for (const d of doc.definitions) if (d.kind === Kind.FRAGMENT_DEFINITION) frags.set(d.name.value, d);
// Collect referenced fragments transitively, starting from the operation.
const used = new Map<string, FragmentDefinitionNode>();
const queue: DefinitionNode[] = [ops[0]];
while (queue.length) {
visit(queue.pop()!, { FragmentSpread(node) {
const f = frags.get(node.name.value);
if (!f) throw new Error(`missing fragment ${node.name.value}`);
if (!used.has(f.name.value)) { used.set(f.name.value, f); queue.push(f); }
} });
}
// Fixed order: operation first, then fragments sorted by name (no locale-dependent compare).
const sorted = [...used.values()].sort((a, b) => (a.name.value < b.name.value ? -1 : 1));
return print({ kind: Kind.DOCUMENT, definitions: [ops[0], ...sorted] }); // one deterministic printer
}
// Fail the build if any key differs from the hash of its re-normalized document.
const manifest: Record<string, string> = JSON.parse(readFileSync(process.argv[2] ?? "persisted-queries.json", "utf8"));
let failed = 0;
for (const [id, doc] of Object.entries(manifest)) {
const recomputed = createHash("sha256").update(normalize(doc), "utf8").digest("hex");
if (recomputed !== id) { console.error(`hash mismatch: key ${id} recomputes to ${recomputed}`); failed++; }
}
if (failed) { console.error(`${failed} mismatched operation(s)`); process.exit(1); }
console.log(`${Object.keys(manifest).length} operations verified`);
A CI check, written in TypeScript with graphql-js, that normalizes each manifest document the way the server does (transitive fragment inclusion, sorted fragments, one printer), hashes it with SHA-256, and fails the build if any recomputed ID differs from its manifest key.
How should you roll out enforcement and handle deploy ordering?
Turning enforcement on in one step is risky, because the first sign of a missed client would be a production outage. Run in log-only mode first. The server accepts every request but records each one that would have been rejected, along with the client name, app version and operation name. Review those logs for a few weeks, long enough to cover release cycles, scheduled jobs and rarely used admin screens. They usually reveal internal tools, scripts and old mobile builds that never went through the manifest pipeline.
The enforcement logic is the same in both modes. Only the final action differs:
- If the request carries a raw query string and no ID, treat it as a violation.
- If it carries an ID, look it up in the in-process cache, then in the manifest store. If the ID is missing, treat it as a violation.
- On a violation, log-only mode records the request and executes it. Enforce mode returns an error and does not execute.
Deploy ordering matters because an ID becomes valid only after the server knows about it. Publish the manifest to the server first, then ship the client. Reversing the order rejects the new client's operations.
Treat the manifest as append-mostly. Installed mobile apps keep sending old IDs for months. Retire an entry only after usage metrics show that no meaningful traffic still comes from the app versions that use it.
The manifest store is a runtime dependency. Cache entries in process, decide whether a store outage should fail open or fail closed, and load a snapshot at startup.
// Server-side persisted query enforcement (language-agnostic pseudocode)
// MODE is "log_only" during rollout, "enforce" once logs are clean.
function handle_graphql_request(req):
id = req.persisted_query_id // hash or ID sent by the client
query = req.query_string // raw GraphQL text, if any
document = null
violation = null
if id is empty and query is not empty:
violation = "raw_query_not_allowed"
else if id is not empty:
document = cache.get(id) // in-process cache first
if document is null:
result = manifest_store.lookup(id) // runtime dependency
if result is STORE_UNAVAILABLE:
// Explicit policy decision: fail open or fail closed
if STORE_OUTAGE_POLICY == "fail_closed":
return error(503, "manifest store unavailable")
violation = "store_unavailable_fail_open"
else if result is NOT_FOUND:
violation = "unknown_persisted_query_id"
else:
document = result.document
cache.put(id, document)
else:
return error(400, "no operation provided")
if violation is not null:
log.warn(violation, client_name = req.header("client-name"),
app_version = req.header("client-version"),
operation_name = req.operation_name, id = id)
if MODE == "enforce" and violation != "store_unavailable_fail_open":
return error(400, "operation not in allowlist") // do not execute
// log_only mode (or fail-open outage): fall back to the raw query
if document is null:
if query is empty: return error(400, "unknown persisted query")
document = query
return execute(document, req.variables)
// At startup: cache.load(manifest_store.snapshot()) before accepting traffic.
Pseudocode for one enforcement path with a log-only/enforce switch, an in-process cache in front of the manifest store, and an explicit fail-open or fail-closed policy for store outages.
How do you handle internal tools, partners and introspection?
Not every consumer ships through your client build. Admin dashboards, partner integrations and engineers running one-off investigations all want to send operations nobody registered in advance. There are three common ways to accommodate them.
Register their operations. Treat a partner or internal tool as another client with its own manifest namespace, submitted through the same review process. This keeps one enforcement path, but it only works when the consumer's operations are known and change slowly.
Run a separate endpoint. Expose a second deployment that accepts arbitrary queries, reachable only from internal networks or through partner-specific credentials. Give it its own depth, complexity and rate limits. The blast radius of an abusive query then stays off the capacity that serves production clients.
Provide an authenticated bypass. Let requests carrying a privileged credential skip the allowlist check on the main endpoint. This is the cheapest option and the riskiest. A leaked token restores exactly the exposure the allowlist removed, so it needs short-lived credentials, a narrow set of holders, and an audit log of every query text that passes through.
| Option | Security exposure | Operational effort | Best fit |
|---|---|---|---|
| Register operations | Lowest | Medium, ongoing review | Stable partners, internal apps with release cycles |
| Separate endpoint | Contained to that endpoint | High, second deployment | Analytics, admin tooling, exploratory partners |
| Authenticated bypass | High if credentials leak | Low to set up, high to audit | Break-glass debugging only |
Decide on introspection explicitly: disable it on the production endpoint and serve the schema from your build artifacts instead. To debug without ad hoc queries, run exploratory queries against staging or a read replica. In production, reproduce issues by replaying a registered operation's hash with captured variables.
What are the alternatives, and how does an allowlist affect engineering cost?
An allowlist answers a single question: is this an operation we shipped? It does not check who is calling, how often, or with which arguments. A registered operation that accepts first: $n can still request a very large page. Use the allowlist alongside the controls below, not as a replacement for them.
| Control | What it limits | Why you still need it with an allowlist |
|---|---|---|
| Depth limits | Deeply nested selections | Cheap backstop if a bad operation gets registered |
| Query cost analysis | Breadth, list sizes, argument-driven cost | Variables still change the cost of registered operations |
| Rate limiting | Request volume per client or token | A known operation can still be called in a flood |
| Resolver-level authorization | Access to specific data | Anyone who has a hash can send it |
| APQ alone | Payload size | Registers any query, so it blocks nothing |
Costs. Client and server releases become coupled, because the manifest must reach the server before the client that depends on it. The manifest pipeline adds CI steps, storage and cleanup work that someone has to own. Mobile apps make retirement slow. You cannot remove an operation, or the fields it uses, until the old app versions that send it have dropped out of use.
Savings. Every request carries an operation ID and name, so you can attribute errors and latency to a specific operation without parsing query text. Performance review covers a finite list of operations, and that review happens at pull-request time. An alert on rejected unknown IDs is useful in two ways. A spike right after a deploy points to a deploy-ordering bug. A steady trickle from a few sources points to probing. Expensive queries nobody wrote in advance can no longer reach production, which removes an entire class of incident.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to graphql persisted queries, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.