Aliases and Fragments

Analogy categoryAnalogies

Aliases Rename Fields in the Response

An alias lets you request a field under a different key in the response JSON by writing aliasName: fieldName before the field, for example featured: user(id: "1"). This solves a specific problem: because a GraphQL response object cannot have two keys with the same name, you cannot request the same field twice with different arguments in one query unless each instance is given a distinct alias to key its result by.

🏏

Cricket analogy: Aliasing striker: batsman(id: "18") and nonStriker: batsman(id: "45") is like a scorecard app labeling two data pulls distinctly instead of both being called 'batsman', the way a live graphic distinguishes Rohit Sharma's stats from Shubman Gill's in the same on-screen panel.

Fragments Reuse Selection Sets Across Queries

A fragment is a named, reusable chunk of a selection set defined with fragment FragmentName on TypeName { ...fields... } and then included elsewhere with the spread operator ...FragmentName. This avoids repeating the same list of fields every time a type shows up in multiple places in a query, or across multiple queries and mutations in a codebase, and it is the mechanism most GraphQL codegen tools rely on to generate matching TypeScript types automatically.

🏏

Cricket analogy: A fragment PlayerCard on Player { name, team, battingAverage } is like a broadcaster defining one reusable lower-third graphic template that gets applied whenever any player — Kohli, Root, or Babar — appears on screen, instead of redesigning the graphic each time.

Inline Fragments for Interfaces and Unions

When a field's return type is an interface or a union — meaning it could resolve to one of several concrete object types — you cannot select type-specific fields directly, because the server can't guarantee every possible type has that field. An inline fragment, written as ... on ConcreteType { fields }, lets you request fields that only exist on one specific concrete type, while shared fields declared on the interface itself can still be selected normally outside any inline fragment.

🏏

Cricket analogy: If a field delivery returns a union of Wicket | Boundary | DotBall, using ... on Wicket { dismissalType } is like a scorecard renderer only pulling 'how out' details when the delivery actually produced a wicket, rather than assuming every ball has a dismissal type.

graphql

fragment PlayerCard on Player {
  id
  name
  battingAverage
}

query CompareOpeners {
  striker: player(id: "18") {
    ...PlayerCard
  }
  nonStriker: player(id: "45") {
    ...PlayerCard
  }
  latestEvent {
    ... on Wicket {
      dismissalType
    }
    ... on Boundary {
      runs
    }
  }
}

Fragments are especially valuable alongside code generation: tools like GraphQL Code Generator emit a matching TypeScript type for every fragment, so a UI component can declare its exact data dependency as a fragment and receive a precisely-typed prop, a pattern widely known as 'colocating data requirements with components'.

Fragments can reference other fragments, but if fragment A spreads fragment B and B spreads A, that circular reference will fail schema validation before the query ever executes — GraphQL fragments must always form a finite, acyclic tree of selections.

An alias (aliasName: fieldName) lets a response key differ from the field name, which is required to request the same field twice with different arguments.
A fragment defines a named, reusable selection set for a given type using fragment Name on Type { ... }.
Fragments are included with the spread operator ...FragmentName and can be reused across many queries and mutations.
Inline fragments (... on ConcreteType) select fields that exist only on one concrete type behind an interface or union.
Shared interface fields can be selected outside any inline fragment; type-specific fields cannot.
Fragments must form an acyclic reference graph — circular fragment spreads fail validation.