Unions and Fragments

Build the mental model

A `union` is similar to an interface but its member types do not need any shared fields — it fits queries that can return unrelated object shapes, like a search result. Querying a union requires inline fragments such as `... on Tutorial` to request type-specific fields. A named fragment (`fragment TutorialCard on Tutorial { ... }`) lets you reuse the same field selection across multiple queries.

Connect it to a real scenario

Model the site-wide search feature with `union SearchResult = Tutorial | Author`. Write a `TutorialCard` fragment once for the card component's field list and reuse it in both the homepage query and the search query — changing the field list means editing just one place.

• Unions need no shared fields among members, for heterogeneous results
• Querying a union needs inline fragments (`... on Type`)
• Named fragments let you reuse field selections

Try the working example

union SearchResult = Tutorial | Author

fragment TutorialCard on Tutorial {
  id
  title
  difficulty
}

query Search($term: String!) {
  search(term: $term) {
    ... on Tutorial {
      ...TutorialCard
    }
    ... on Author {
      id
      name
    }
  }
}

You can query a union type and reuse a field selection with a fragment.

GraphQL — Queries and Mutations (Fragments) — GraphQL