Named Fragments

## A fragment is a definition, not a schema construct An executable GraphQL document is a list of definitions, and only two kinds may appear in it: operation definitions (`query`, `mutation`, `subscription`) and **fragment definitions**. A fragment definition has exactly three parts - a name, a **type condition** introduced by `on`, and a selection set: ```graphql fragment ClaimSummary on Claim { claimNumber status reserveCents policy { policyNumber } } ``` None of this reaches the schema. The server does not gain a type, a field or a capability called `ClaimSummary`; the name exists for the lifetime of the request document and nowhere else. Two different callers may each define `ClaimSummary on Claim` with completely different fields, and neither is aware of the other. That is the first thing to be clear about in an interview: a fragment is client-side vocabulary carried inside the request. ## The spread substitutes, it does not nest A **fragment spread** - three dots followed by the name - appears as a selection inside a selection set, alongside ordinary fields: ```graphql query ClaimsQueue { openClaims { ...ClaimSummary } escalatedClaims { ...ClaimSummary } } ``` The executor expands the spread in place, so what comes back is flat: ```json {"data":{"openClaims":[{"claimNumber":"CLM-88214","status":"OPEN","reserveCents":412500,"policy":{"policyNumber":"POL-3391"}}],"escalatedClaims":[]}} ``` There is no key called `ClaimSummary` anywhere in that response, and there never can be. A candidate who expects a nested object named after the fragment has confused a spread with a wrapper. ## The rules the syntax carries **Names are unique within a document.** A document containing two definitions named `ClaimSummary` is invalid whatever their type conditions or contents, and it is rejected before anything executes. This bites when a caller assembles one document out of fragments authored in different places; the usual defence is a naming convention that prefixes each fragment with the view or module that owns it. That convention is a house style, not a rule in the specification - the specification only demands uniqueness inside the one document being sent. **The type condition must be a composite output type** - an object type, an interface or a union. `fragment Amount on Int` is invalid: a scalar has no selection set, so there is nothing for the fragment's body to be checked against. Input object types are ineligible for the same reason; fragments belong to output selection. **Definitions are unordered.** A fragment may be defined after the operation that spreads it, between two operations, or at the very end of the document. Unlike a variable, which must be declared on the operation that uses it, a fragment has no declaration-before-use rule - the whole document is parsed before anything is checked. **Fragments may spread other fragments.** A fragment's selection set is an ordinary selection set, so a fragment can itself contain `...PolicyStamp`. Nesting simply flattens; a fragment may not, directly or through a chain, end up spreading itself. ## Why they are worth having Reuse and readability, in that order. In a claims graph the same "who, what, how much" block is wanted on the queue screen, on the detail screen and in the nightly export, and factoring it out means one edit instead of three. It also keeps very deep documents legible: the deepest document in one insurer's caller bundle reaches 19 levels - claim, related claims, their events, the assigned adjuster, that adjuster's own queue - and reading it at all depends on each level being one named spread rather than forty inline fields. What fragments do **not** buy is server work. A spread resolves exactly the fields it lists, exactly as if they had been typed inline. There is no caching by fragment name, no reuse across requests, and no reduction in resolver calls. The only saving is in the bytes of the request, and only when a fragment is spread more than once. ## Not a function The specification's fragments take no arguments of their own. A fragment can reference variables - a field inside it may carry `@include(if: $showFinancials)` - but those variables belong to the *operation*, and every operation that spreads the fragment must define every variable used anywhere inside it, transitively. Proposals to give fragments their own parameters have circulated for years; a portable document cannot assume them today. A candidate who describes a fragment as "a function you call with arguments" is usually describing an extension a particular client tool added, not GraphQL. ## Saying it in an interview Lead with the definition-plus-spread mechanic and the fact that the response is flat, then the type condition, then uniqueness. If you have thirty seconds more, add the two facts most people get wrong: fragments are invisible to the schema, and they save request bytes rather than server work.