Union types in GraphQL - Step-by-Step Execution

Concept Flow - Union types

Query requests a Union field

↓

GraphQL server checks the actual type

↓

Matches one of the Union member types

↓

Returns data shaped as that member type

↓

Client reads data with __typename to identify type

A GraphQL query asks for a field that can be one of several types. The server figures out which type it is and returns data accordingly. The client uses __typename to know the actual type.

Execution Sample

GraphQL

union SearchResult = Photo | Person
query {
  search(text: "sun") {
    __typename
    ... on Photo { url }
    ... on Person { name }
  }
}

This query searches for 'sun' and returns results that can be either Photo or Person, including type info and specific fields.

Execution Table

Step	Action	Type Checked	Matched Type	Returned Fields	Output Example
1	Query 'search' with text 'sun'	N/A	N/A	N/A	N/A
2	Server finds first result	SearchResult	Photo	url	{ __typename: "Photo", url: "sunrise.jpg" }
3	Server finds second result	SearchResult	Person	name	{ __typename: "Person", name: "Sunny" }
4	Client reads __typename to know type	N/A	N/A	N/A	Client sees type and fields accordingly
5	No more results	N/A	N/A	N/A	Query ends

💡 All search results processed and returned with their specific types.

Variable Tracker

Variable	Start	After 1	After 2	Final
searchResult[0]	undefined	{ __typename: "Photo", url: "sunrise.jpg" }	{ __typename: "Photo", url: "sunrise.jpg" }	{ __typename: "Photo", url: "sunrise.jpg" }
searchResult[1]	undefined	undefined	{ __typename: "Person", name: "Sunny" }	{ __typename: "Person", name: "Sunny" }

Key Moments - 2 Insights

Why do we need __typename in the query?

Because the field can return different types, __typename tells the client which type each result is, so it knows which fields to expect. See execution_table step 4.

What happens if the server returns a type not in the Union?

The server must only return types defined in the Union. Returning another type would cause an error or invalid response. This is shown in execution_table steps 2 and 3 where only Photo or Person are matched.

Visual Quiz - 3 Questions

Look at the execution_table, what is the __typename of the first search result?

A SearchResult

B Person

C Photo

D sunrise.jpg

💡 Hint

Check execution_table row 2 under 'Output Example' and 'Matched Type'

At which step does the client identify the type of the returned data?

A Step 4

B Step 2

C Step 3

D Step 5

💡 Hint

Look at execution_table step 4 where client reads __typename

If the Union included a third type 'Album', how would the execution_table change?

A The server would return only Photos

B There would be a step with Matched Type 'Album' and its fields

C The client would not need __typename anymore

D The query would fail

💡 Hint

Adding a new Union member means server can return that type, so execution_table would show it

Concept Snapshot

Union types let a field return one of several types.
Use __typename in queries to know which type is returned.
Server checks actual type and returns matching fields.
Client uses fragments to get fields for each type.
Useful for flexible search or polymorphic data.

Full Transcript

In GraphQL, union types allow a field to return different types of data. When a query requests a union field, the server checks which actual type the data is and returns it with a __typename field. This helps the client know which type it received and which fields to expect. For example, a search query might return photos or people. The client uses fragments to get fields specific to each type. This visual trace shows the server matching types and returning data step by step, and the client reading the type information to handle the results correctly.