Operations & Documents

Validation compares the parsed document against the schema alone: each selected field must exist on its type, each required argument must be supplied, and each fragment must be used and acyclic. A document that fails runs no resolvers.

They let the client decide at request time whether part of its own selection is sent. @include(if:) keeps a selection only when its boolean is true; @skip(if:) drops it when true. An excluded selection is simply absent from the response.

Fragment colocation is a client convention: every view declares the fields it needs as its own GraphQL fragment, stored beside that view, and a parent composes those fragments upward into one operation per screen.

An inline fragment is an unnamed ... on SomeType { ... } block inside a selection set. You need one when a field returns an interface or a union and you want fields that exist only on one concrete type.

A named fragment is a reusable selection set declared once at the top level of a document, on a type condition, and pulled into a selection with the three-dot spread. Its fields land in the response exactly as if written inline.

Query, mutation and subscription. Each enters the schema through its own root type and carries a different intent: a read, a write followed by a read of the result, and a long-lived stream of events. Only the query root is required.

A selection set is the brace-delimited list of fields a GraphQL document requests at one level. A field whose type is an object, interface or union must carry one; a field whose type is a scalar or enum must not.

A GraphQL variable is a named, typed placeholder declared on the operation and filled from a separate values map sent with the request. Only input types are allowed: scalars, enums, input objects, and their list or non-null wrappers.

Omitting an argument means no value was provided, so the schema's declared default applies. Writing null provides a value, so the default is not substituted and the server receives an explicit null.

Three phases in order: parse the text into a syntax tree, validate that tree against the schema, then execute. A syntax error ends the request at parse, so nothing is validated, no resolver runs, and the response has errors and no data key.

By the operationName the caller supplies. With exactly one operation in the document the name may be omitted; with two or more, a missing or unmatched operationName is a request error and nothing executes.

Before execution the server coerces each supplied value to its declared type: scalars by strict per-type rules, enums from a string matching a member name exactly, lists item by item. A value that will not coerce is a request error.

Whitespace, line breaks, a leading byte-order mark, comments running from a hash to the end of the line, and commas. Commas are ignored tokens rather than separators, so a document parses identically with all of them, some, or none.

The field is excluded. When both directives apply to one selection, it survives only if the @skip condition is false and the @include condition is true, so a true @skip removes it whatever @include says.

To a schema type, never to the view. A fragment written on Order says only give me an Order, so any parent selecting a field of that type can spread it, and renaming the view changes nothing.

Because matched inline-fragment fields arrive flat, the response alone does not say which branch applied. __typename is a meta-field returning the concrete object type's name, so it is the discriminator a client branches on.

A fragment may be spread into any selection set whose type could actually be the fragment's type condition - the two must share at least one possible object type. The type condition also fixes which fields the fragment is allowed to select.

Only when the document holds exactly one operation, that operation is a query, and it declares no variables and carries no directives on the operation itself. Then both the query keyword and the operation name may be omitted.

An alias, written alias: field, renames the key a field appears under in the response. You need one to select the same field twice at one level with different arguments, because two selections sharing a response key must otherwise be identical.

Inlining makes the document text change with every value, so two runs of one operation are two different documents. That wrecks document-keyed metrics, allowlists and caches, and drops user data into logged query text.

A syntax error proves the schema, resolvers and data stores never ran, so the fault is in the bytes the client sent. Capture that exact document text, read the error's line and column against it, and inspect how the client assembles it.

Validation compares a document only to the schema. A list field whose paging argument is optional is a legal selection however many rows come back, so nothing static can object. The bound must come from the schema and a resolver clamp.

They gate whole selections and nothing else: no else keyword, no way to vary an argument, no condition that reads data in the same response. And a skipped field is still validated, so it cannot hide a removed one.

A nested view cannot form its query until its parent's response supplies the id it needs, so round trips run in series. Colocation hoists every view's fields into one operation the screen sends before rendering.

It receives the object with none of its branch fields — only what was selected outside the branches, which on a union is at most __typename. Nothing errors; the document stays valid and the row simply arrives empty.

Selection sets fix the response shape — only selected keys come back — and nesting removes dependent round-trips. They do not stop a client selecting fields nothing renders, do not shrink backend work, and cannot remove a round-trip that waits on a returned value.

Omitting a variable leaves it not provided, so the argument falls back to its schema default. Sending null provides a value, which overrides that default and reached a resolver that read null as no limit.

A string literal delimited by triple quotes that may span lines and contain unescaped quotes. The parser normalises line endings, strips the indentation common to every line after the first, and removes leading and trailing blank lines.

Spreading a fragment inlines its selections rather than calling it, so two fragments that spread each other denote a selection set with no end. The specification makes cycles a validation error, so such a document fails before execution.