Why should a GraphQL caller put user-supplied values in variables rather than inline literals?

## The document text is the operation's identity A GraphQL request carries a document, and almost everything a platform builds on top of GraphQL keys off that document's text or a hash of it. When the values are written inline, the text changes every time a value changes, so two requests that a human would call "the same operation" are two different documents to every system downstream. Consider a course-enrolment API. Written with literals, one caller sends: ```graphql mutation { enroll(sectionId: "SEC-4471", status: WAITLISTED) { enrollmentId } } ``` and the next sends the identical text with `SEC-4472`. Written with variables, both send one document and a separate map of values. That is the whole difference, and it decides four separate things. ## What is keyed on the document **Per-operation metrics and traces.** Server and tracing tooling group work by operation, usually by operation name plus a document hash. With literals inlined, one logical operation fans out into as many distinct documents as there are argument values. At a 1,200-request-per-minute peak an inlined-literal mutation can produce well over a hundred thousand distinct document texts in a day, and the per-operation latency view that should have one row has a hundred thousand rows of one sample each. Nothing is measurable at that cardinality. **Registered-document allowlists.** A deployment that only accepts documents registered at build time has to register every distinct text. If the values are inlined, the set of texts is unbounded and the control is unusable — you cannot enumerate a set that depends on runtime data. **Parse and validate caches.** Servers commonly cache the parsed and validated form of a document keyed by its text, because parsing and validating is real work that repeats on every request. A document that is textually unique every time gets no cache hits, so that work is paid in full at every request instead of once per operation. **Response and edge caches.** A cache in front of the server keys on the request; a document whose text varies per value has no shared key to hit. ## Log hygiene The document is the part of the request that is most likely to be logged, attached to a trace span, or included in an error report, because it is the thing a human needs to see to understand what happened. Values inlined in that text go wherever the text goes. Student identifiers, email addresses and free-text notes end up in query logs and vendor traces, and they are extremely hard to remove afterwards because they are inside an opaque string rather than in a labelled field. With variables, the document is stable and value-free, and the variables map is a separate object you can redact, sample or drop wholesale. ## The string-building hazard There is no way to inline a runtime value except to build the document by concatenating text. That is a familiar hazard in a new place. It is not equivalent to SQL injection — the resulting document is still parsed and validated against the schema, so nobody can conjure a field that does not exist or reach past the schema into the datastore. But a value containing a quote can terminate the string literal early and change what the document *asks for*: extra fields in the selection set, a different argument, or a second operation appended after the first. Everything it can reach is schema-legal, which is exactly why it does not look like an attack in the logs. Variables remove the class entirely, because the value never passes through the parser. ## When a literal is still correct The rule is not "never write a literal". A literal is right when the value is part of what the operation *means* and is the same for every caller: a fixed page size, an enum that selects which branch of a filter this named operation represents, a constant flag. Those values belong in the document because they are not data — changing one produces a genuinely different operation, and it should get a different document and a different name. A useful test: if changing the value would not change what you would call the operation in conversation, it is data, and data belongs in variables. There is a small bonus for genuine constants. Because a literal is checked statically against the schema, a typo in a constant fails identically for every caller and shows up the first time anyone runs the document, rather than for one user whose input happened to trigger it. ## Diagnosing it on a running system You rarely get told that clients are inlining values; you find it. Take the server's request log or trace attributes, group by operation name, and count distinct document hashes per name. A healthy name has a handful — one per deployed client version. A name with thousands of hashes is a client building documents by concatenation, and the count itself is the argument you take to that team.