Query Variables

Queries Built by String Concatenation Fail Twice

The tempting way to make GraphQL dynamic is to build the document with string interpolation:

const query = `query { user(id: "${userId}") { email } }`;

It fails in two independent ways.

Injection. userId is caller-controlled input, and GraphQL parses whatever string arrives. Send:

1") { role admins: admins { email } } #

and the caller has written server-side schema traversal you never intended — the same class of bug SQL hands you when a WHERE clause is concatenated. Field-level authorization may catch it, but you never asked for it.

Cache fragmentation. Every distinct value becomes a distinct document. Ten thousand users produce ten thousand unique query strings in the CDN, the automatic-persisted-query store, and any document cache — all identical except for one literal, so nothing can be shared.

The fix separates shape from data:

const query = 'query User($id: ID!) { user(id: $id) { email } }';
const variables = { id: userId };

The document is now a constant that can be hashed, persisted, and cached once; the value travels as data where it is validated and coerced instead of parsed as syntax. See persisted queries for how that constant document becomes an id on the wire.

A third failure is quieter but real: debugging. With interpolated text, the query a user actually sent exists only in that user's request log, so reproducing a bug means reconstructing the string by hand. With variables, every failing request records the same document plus its inputs — one artifact to reproduce, one to cache, one to review in a pull request.

The pattern is not GraphQL-specific. Anything derived from user input belongs on the value side of a protocol — SQL parameters, template data, header values — never on the structure side. When a framework lets you choose, the choice determines whether input can ever become syntax.

Definition, Usage, Delivery

A variable appears in three places, each with its own rule:

query GetUser($id: ID!, $withEmail: Boolean! = true, $first: Int = 10) {
  user(id: $id) {
    name
    email @include(if: $withEmail)
    posts(first: $first) { title }
  }
}

Over HTTP the two halves travel separately:

{
  "query": "query GetUser($id: ID!, $withEmail: Boolean! = true, $first: Int = 10) { ... }",
  "variables": { "id": "7", "withEmail": false }
}

Execution proceeds in four phases, and each failure mode is tied to one of them:

1. Syntax — the document parses, or the request dies immediately with a syntax error.
2. Validation — declarations are checked against usage. $first: String used for an Int! argument returns Variable "$first" used in position expecting type "Int!". Nothing has been read from the database yet.
3. Coercion — the supplied JSON values are converted to the declared types; a declared default fills an omitted variable. A non-null variable with no value short-circuits here with a request error naming it, rather than executing a half-specified query.
4. Execution — user(id: $id) and @include(if: $withEmail) read the coerced values.

Knowing the phase tells you who must fix the bug: a missing variable is the client's contract violation, a resolver's null is the server's data problem.

Non-Null Contracts, Defaults, and Cache Keys

Variable declarations are a published contract with every caller of the operation:

query Feed($first: Int! = 25, $after: String, $orderBy: Order = NEWEST) {
  posts(first: $first, after: $after, orderBy: $orderBy) {
    id
    title
  }
}

• $first: Int! = 25 — callers may omit it and get 25, but the resolver never has to handle null. Remove the default and every client must send a value.
• $after: String (nullable) — null means "start at the beginning," which is a legitimate value in cursor pagination, so it stays nullable.
• Type compatibility is enforced at validation, not execution. A nullable variable cannot satisfy a non-null position; a non-null variable is accepted where a nullable one is expected.

The caching consequence. The document text is now constant, so a cache keyed only on the query hash returns the first caller's data for every later request. The key has to include the variables, or personalized queries must stay out of shared caches entirely:

// wrong:  key = sha256(document)
// right:  key = sha256(document) + stableStringify(variables)

One coercion rule worth knowing. A variable supplied as JSON null for a nullable variable passes null through to the argument — it does not fall back to the argument's default value, because the argument was supplied. Defaults apply only when the argument is omitted altogether; a non-null argument receiving that null fails with an error instead.

Interview angle: walk the four phases (syntax → validation → coercion → execution), give the error each produces, then explain that constant document text is simultaneously a security property (no input parsed as syntax) and a caching property (one entry per operation).

One caching detail to add: an operation name travels with the document, so a shared cache key should cover document text, operation name, and variables together. In a client that bundles several operations into one file, two different operations can share a single HTTP request body — operationName is what selects which one executes.