What is an inline fragment in a GraphQL query, and when do you need one?

## The problem an inline fragment exists to solve A GraphQL document is written against the **schema**, but a field whose declared type is abstract — an interface or a union — does not tell the document what will actually be there. In a warehouse inventory graph, a bin's `contents` might be declared as a union of `Pallet`, `LooseCase` and `ReturnTote`. Every one of those has different fields. The document is static text; the concrete type is a runtime fact. So GraphQL splits the selection into a common part and conditional parts. The conditional part is a **fragment with a type condition**, and when you only need it once, in one place, you write it inline. ## Syntax and shape ```graphql query BinContents($binId: ID!) { bin(id: $binId) { contents { __typename ... on Pallet { sscc grossWeightKg } ... on LooseCase { caseGtin quantity } } } } ``` The `...` is the spread token, `on Pallet` is the **type condition**, and the braces hold a selection set like any other. There is no name and no definition elsewhere in the document — that is the whole difference from a named fragment, which is declared once and spread by name wherever it is needed. Choose inline when the branch is used in exactly one place; extract a named one when it is reused or when a client tool wants to own it. ## Interfaces and unions behave differently * An **interface** declares fields that every implementing type has. Those you may select directly on the abstract field, with no narrowing at all. You reach for an inline fragment only for the fields that exist on *one* implementation. * A **union** declares no fields whatsoever — it is only a list of possible object types. A selection set on a union may therefore contain only `__typename` and fragment spreads. Writing a plain field on a union is a validation error, even if every member happens to have a field by that name. That asymmetry is the single most common source of confusion, and it is worth being able to state without hesitating. ## The scope rule A type condition is not free-form. The specification requires that the condition's possible types and the enclosing type's possible types **overlap** — informally, that the fragment could ever apply where it is written. Narrowing `contents` to `... on Pallet` is fine because `Pallet` is a member of that union. Narrowing it to `... on Carrier`, a type that is not a member, is rejected during validation, before anything executes. The point of the rule is that a fragment which could never match is almost always a mistake, not a harmless no-op. A type condition may also be *wider* than the enclosing type, or equal to it. `... on InventoryNode { ... }` inside a selection on `Pallet` is legal if `Pallet` implements that interface — it just always matches. ## Branches are filters, not a switch statement This is where mental models go wrong. Inline fragments do not behave like a `switch` where exactly one arm runs. During execution the server determines the concrete object type at that position, then collects fields from the enclosing selection set **plus every inline fragment whose type condition matches**. If two branches both match — an interface branch and a concrete-type branch, say — both contribute, and their fields are merged. And the result is **flat**. The response object for a matching `Pallet` carries `sscc` and `grossWeightKg` as ordinary keys alongside `__typename`; there is no per-branch wrapper in the JSON: ```json { "__typename": "Pallet", "sscc": "00370412998415", "grossWeightKg": 612.4 } ``` Fields from a branch that did **not** match are simply absent — not present-and-null. A consumer that does an unconditional property read on a field it only asked for under one branch will find nothing there for the other members. ## What an interviewer is checking Three things, usually in one answer: that you know an abstract field cannot be selected concretely without narrowing; that you can name the difference between what an interface and a union let you select without a fragment; and that you know the matched fields come back flat, with the unmatched ones missing rather than null. If you can add that the type condition must be able to overlap the enclosing type, you are past the screening bar for this topic.