Persisted Document Registries

## The document leaves the client at build time, not at request time A GraphQL client normally carries its operations as text and sends that text on every request. A persisted-document registry moves the text out of the request entirely, one release ahead of time. The move happens during the build. A tool walks the client source, collects every GraphQL document it can find — string constants, tagged template literals, `.graphql` files — and for each one produces a pair: an identifier, and the exact document text that identifier stands for. Those pairs are written into a **manifest**, which is nothing more than a map from identifier to document. The manifest is published to the server. The client artefact that ships alongside it no longer contains query text; where the text used to sit, the build has substituted the identifier. The identifier is usually a cryptographic hash of the document text, because a hash needs no coordination — two builds of the same operation agree on it without talking to each other, and any change to the operation produces a different one. Nothing requires a hash: sequential numbers or `release/operationName` work equally well, because the identifier is opaque to the server, which needs only a key it can look up. What does matter is that the text is **normalized before it is hashed** — canonical whitespace, comments stripped, fragments emitted in a stable order — so that a reformat with no semantic change does not mint a second entry for the same operation. ## What travels Three things: the identifier, the variable values, and an operation name where the stored document defines more than one operation. The variables are unchanged from an ordinary request — they are per-call data, and folding them into the identifier would defeat the whole scheme by minting an entry per value. For the same reason, interpolating a value into the document text instead of passing it as a variable produces a distinct document, and therefore a distinct registry entry, for every value. There is no specified field name for the identifier. The GraphQL specification defines the language and the execution algorithm and says nothing about how a request travels; the GraphQL over HTTP specification governs the transport. Persisted documents sit on top as a convention, so the request parameter, the manifest format and the behaviour on a miss are agreements between one client build and one server rather than portable guarantees. Say that plainly in an interview — it separates people who have run this from people who have read about it. ## The server side is a lookup, not a negotiation On receiving a request the server takes the identifier, looks it up in whatever store holds the registry, and — if it finds an entry — proceeds exactly as if the client had sent the text: parse it (or reuse an already-parsed form), validate it against the schema, select the operation, execute with the supplied variables. If it finds no entry there is nothing to execute, and it answers with an error rather than a result. The absence of a fallback is the defining property. A related convention derives the same kind of identifier at runtime and lets a client teach the server the text when the server has not seen it; a build-time registry deliberately does not, because the text is not in the shipped artefact to send. That single design choice is where every deploy-ordering and retention consequence comes from. ## What the identifier does and does not identify It identifies **one document**, byte-for-byte after normalization. It does not identify a response, a user, a schema version or a result set. Interviewers probe this because the identifier looks so much like a cache key that people reach for it as one, and a shared cache keyed on the identifier alone ignores both the variables and the viewer. On a freight-tracking graph, one `TrackConsignment` identifier sent by two accounts is one key and two entirely different answers — which is how a cache serves one shipper the other's consignment row. Nor is the manifest discoverable. The server does not learn it by introspection or by watching traffic; something in the release process put it there. ## What you buy and what you give up The gains are concrete: requests shrink from kilobytes of document text to a short key; the server only ever executes documents that existed in a build; and a short key is small enough to ride in a URL, which reopens transport options that a body-carried document closes off. The loss is equally concrete: nothing new can be asked at runtime. Any tool, script or ad-hoc exploration that composes a query on the fly is either excluded or needs a separate path that accepts document text — an authenticated route, a non-production endpoint, or a second server. Deciding which of those you offer, and to whom, is a real design question rather than an afterthought.