Inline Fragments on Unions and Interfaces

The Field That Does Not Exist on This Type

A search endpoint returns posts, users, and comments — three unrelated types sharing nothing but id. In SDL that is a union:

type SearchResult = Post | User | Comment

Selecting a type-specific field directly fails validation:

query Broken {
  search(term: "graphql") {
    title        # ✗ Cannot query field "title" on type "SearchResult"
  }
}

A union declares no fields of its own beyond __typename, so there is nothing for title to bind to — the validator checks the document against the declared shape, not against the data that happens to be stored.

An inline fragment narrows the selection to one member type without naming a reusable fragment first:

query Search($term: String!) {
  search(term: $term) {
    __typename
    ... on Post    { id title author { name } }
    ... on User    { id name avatarUrl }
    ... on Comment { id body }
  }
}

... on Post reads as "when this element is a Post, select these fields." Validation now checks title against Post and avatarUrl against User, both of which declare them, so the document passes.

Two properties of the syntax are worth pinning down:

• The condition is a type, not a name. ... on Post asserts the runtime type of the element, and validation checks that assertion against the enclosing selection: spreading ... on Post inside a selection of Comment fails with Fragment cannot be spread here as objects of type Comment can never be of type Post whenever the two types cannot overlap.
• Inline means there is nothing to declare elsewhere. A named fragment needs a name, a home, and a reuse argument. When a type condition appears in one query only, the inline form keeps the test next to the fields it guards, with no second file to open.

Conditions are evaluated per element during execution, so one document can carry a branch for every member type and each element still executes only its own — the other branches cost nothing for that element.

Type Conditions at Runtime

The server executes only branches whose condition matches the element's runtime type, then merges everything into one flat object per element:

{
  "data": {
    "search": [
      { "__typename": "Post",    "id": "1", "title": "GraphQL in practice", "author": { "name": "Ada" } },
      { "__typename": "User",    "id": "9", "name": "Grace", "avatarUrl": "/g.png" },
      { "__typename": "Comment", "id": "4", "body": "Nice write-up" }
    ]
  }
}

What that response tells you:

• Shared fields belong outside the conditions. id and __typename are requested once and appear on every element, so a render loop can key records before it knows anything about type.
• A missing key is the discriminator. The Post element has no avatarUrl key at all — not null. Branch on __typename first, then read type-specific keys inside that branch.
• Unmatched branches produce nothing, not nulls. The User element simply omits title and body; elements are never padded with nulls to look uniform.
• Interfaces behave differently at the top level. Any field declared on the interface is selectable directly, and inline fragments are needed only for fields declared on one implementer. Unions expose nothing but __typename.
• Directives attach to inline fragments. ... on Post @include(if: $showPosts) { title } hides an entire member type conditionally — see include and skip directives.

If the same element must satisfy two conditions — a Post that also implements a Featured interface, selected with both ... on Post and ... on Featured — both branches execute and their fields merge into that one element. Conditions are tests, not branches of an either/or: every matching condition runs, and only non-matching ones are skipped.

Exhaustiveness, Codegen, and Named Fragments

Nothing forces a document to cover every member of a union. Omit ... on Comment and validation passes: comment elements come back with only the shared keys, and a renderer that assumes title exists crashes on that one element. Exhaustiveness is a client discipline, and generated types are how you enforce it:

type SearchResult =
  | { __typename: 'Post';    id: string; title: string; author: { name: string } }
  | { __typename: 'User';    id: string; name: string; avatarUrl: string }
  | { __typename: 'Comment'; id: string; body: string };

function render(r: SearchResult): string {
  switch (r.__typename) {        // compiler flags any missing case
    case 'Post':    return r.title;
    case 'User':    return r.name;
    case 'Comment': return r.body;
  }
}

Codegen derives that discriminated union from the schema, so adding a member type turns every non-exhaustive switch into a build error — see TypeScript codegen.

Choosing between inline and named fragments:

Named fragments with concrete type conditions spread perfectly well inside a polymorphic selection, so reuse and type conditioning are independent tools rather than an either/or.

Interview angle: "How does the client know which member type it received?" — __typename, read before branching; then explain why an omitted branch yields an element with only shared keys instead of an error, and why that makes exhaustive switches non-negotiable.