Variables & Coercion

## The split a variable creates A GraphQL request carries two things: a **document**, which is the text describing what to fetch, and a **variable values map**, which supplies the parameters. A variable is the joint between them. Declaring one tells the server "this operation takes a parameter of this type"; referencing `$name` inside the operation says "put its value here". The values themselves arrive as an ordinary keyed map alongside the document, most often JSON. That split matters because the document is *structure* and the values are *data*. A music catalogue client that shows one playlist screen has exactly one document, whatever playlist the user opened. The document is written once, checked once against the schema, and reused; only the map changes between calls. ## The grammar Variables are declared on the **operation**, in parentheses after the operation name, and nowhere else - not on a field, not on a fragment definition: ```graphql query PlaylistTracks($id: ID!, $first: Int = 25, $markets: [Market!]) { playlist(id: $id) { name tracks(first: $first, markets: $markets) { id title } } } ``` Each entry is `$name: Type` with an optional `= default`. The `$` is part of the reference syntax, not part of the name in the values map: the map key here is `"id"`, not `"$id"`. A variable can be used as a whole argument value, as a field of an input object literal, or as an item inside a list literal - anywhere the grammar admits an input value. ## Only input types The specification restricts a variable's declared type to an **input type**, and the rule is enforced during validation: - built-in and custom **scalars** (`Int`, `Float`, `String`, `Boolean`, `ID`, and anything the schema declares with `scalar`), - **enums**, - **input object types**, - and any **list** (`[T]`) or **non-null** (`T!`) wrapping of those. Declaring `$track: Track` where `Track` is an object type is invalid, and so is a variable typed as an interface or a union. The reason is direct: a caller sends *values*, and object, interface and union types describe things a server *returns*, whose shape depends on the selection set the document asked for. There is no way to write one down as an argument. This is also why a schema tends to grow a parallel family of input types - a `TrackFilterInput` beside a `Track` - rather than reusing output types for arguments. ## Defaults A variable definition may carry a default value: ```graphql query Chart($first: Int = 25, $market: Market! = GB) ``` Two details are worth holding on to. First, the default must be a **constant literal** - a number, a string, an enum name, a list or input object built from constants. It cannot reference another variable, because there is no ordering in which variables are resolved against each other. Second, a **non-null** variable may still carry a default. `$market: Market! = GB` is perfectly legal: the caller may omit `market` and get `GB`, but may not send `null` for it, because null is not a value of a non-null type. ## The document-level rules around variables Beyond the type restriction, a handful of validation rules govern variables in a document. Variable names are **unique within an operation**. Every variable a document *uses* must be **declared** by the operation that runs it, and every variable a document *declares* must be **used** - an unused declaration is an error, not dead weight the server tolerates. Because a named fragment cannot declare variables of its own, a fragment that references `$first` inherits the requirement: every operation that spreads that fragment, directly or transitively, must declare `$first`. There is also a compatibility rule between a variable's declared type and the argument position it lands in. A variable typed `Int!` may be used where `Int` is expected; a variable typed `Int` may **not** normally be used where `Int!` is expected, since a nullable variable could arrive as null in a position that forbids it. That is relaxed when a default rescues it - either the variable definition has a non-null default, or the argument itself declares one - because then no request can leave the position empty. ## What a variable is not A variable is not text substitution. The server does not paste the value into the document and re-parse it; the parsed document holds a *reference* to a variable, and the value is resolved separately when the request is executed. A consequence a beginner is often surprised by: a variable cannot stand in for a **field name**, an **alias**, a **type condition**, or a **directive name**. `$fieldName { ... }` is not a thing. Variables parameterise values only; if the client needs a different shape, it needs a different document, or an executable directive to include and skip parts of the one it has. A final practical note: variables never appear in the response. The response echoes the document's response keys and the data behind them, and knows nothing about how the arguments were supplied.