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.

Practice

1. What is the main purpose of using union types in GraphQL?

easy

A. To group multiple object types into one field that can return different types

B. To define a list of scalar values

C. To create a new scalar type

D. To enforce a single object type for a field

Solution

1. Step 1: Understand union type purpose

   Union types allow a field to return one of several object types, grouping them logically.

2. Step 2: Compare with other options

   Defining a list of scalar values or creating a new scalar type describes scalars, not unions. Enforcing a single object type for a field contradicts the union concept.

3. Final Answer:

   To group multiple object types into one field that can return different types -> Option A

4. Quick Check:

   Union types = group multiple object types [OK]

Hint: Unions group different object types under one field [OK]

Common Mistakes:

• Confusing union with scalar types
• Thinking unions enforce a single type
• Mixing unions with interfaces

2. Which of the following is the correct syntax to define a union type named SearchResult that includes User and Post types?

easy

A. type SearchResult = User & Post

B. union SearchResult = User | Post

C. interface SearchResult = User | Post

D. union SearchResult { User, Post }

Solution

1. Step 1: Recall union syntax

   Unions use the syntax: union Name = Type1 | Type2 with pipe separators.

2. Step 2: Check each option

   union SearchResult = User | Post matches correct syntax. type SearchResult = User & Post uses & which is for intersections, not unions. interface SearchResult = User | Post wrongly uses interface keyword. union SearchResult { User, Post } uses braces which is invalid for unions.

3. Final Answer:

   union SearchResult = User | Post -> Option B

4. Quick Check:

   Union syntax uses '=' and '|' [OK]

Hint: Use '=' and '|' to define unions, no braces [OK]

Common Mistakes:

• Using '&' instead of '|'
• Using braces {} instead of '='
• Confusing union with interface syntax

3. Given the union type SearchResult = User | Post and this query:

{ search { ... on User { name } ... on Post { title } } }

What fields will be returned if the search result contains one User with name "Alice" and one Post with title "GraphQL Guide"?

medium

A. [{"name": "Alice"}]

B. [{"name": "Alice", "title": "GraphQL Guide"}]

C. [{"title": "GraphQL Guide"}]

D. [{"name": "Alice"}, {"title": "GraphQL Guide"}]

Solution

1. Step 1: Understand inline fragments on union

   The query uses inline fragments to select name from User and title from Post.

2. Step 2: Apply to data

   Since the result has one User and one Post, the response includes both objects separately with their respective fields.

3. Final Answer:

   [{"name": "Alice"}, {"title": "GraphQL Guide"}] -> Option D

4. Quick Check:

   Inline fragments return fields per type separately [OK]

Hint: Inline fragments return separate objects per type [OK]

Common Mistakes:

• Combining fields into one object
• Returning only one type's fields
• Ignoring inline fragment usage

4. Consider this union definition:

union SearchResult = User | Post

And this query:

{ search { ... on User { id name } ... on Post { id title } } }

Which of the following errors will occur if you try to query a field email inside Post inline fragment like this:

{ search { ... on User { id name } ... on Post { id title email } } }

medium

A. Error: Field 'email' must be queried on User type

B. No error, query runs successfully

C. Error: Field 'email' does not exist on type 'Post'

D. Error: Union types cannot have inline fragments

Solution

1. Step 1: Check Post type fields

   If email is not defined on Post type, querying it causes an error.

2. Step 2: Understand inline fragment validation

   Inline fragments must only query fields existing on the specified type. Querying unknown fields causes errors.

3. Final Answer:

   Error: Field 'email' does not exist on type 'Post' -> Option C

4. Quick Check:

   Querying unknown fields on type causes error [OK]

Hint: Check if field exists on type before querying [OK]

Common Mistakes:

• Assuming all fields exist on all union types
• Thinking unions disallow inline fragments
• Querying fields on wrong types

5. You have a union type SearchResult = User | Post | Comment. You want to write a query that returns the name for User, title for Post, and content for Comment. Which query correctly fetches these fields?

hard

A. { search { ... on User { name } ... on Post { title } ... on Comment { content } } }

B. { search { name title content } }

C. { search { ... on User { name } ... on Post { title } content } }

D. { search { ... on User { name } ... on Post { title } ... on Comment { title } } }

Solution

1. Step 1: Use inline fragments for each union type

   Each type in the union requires its own inline fragment to query its specific fields.

2. Step 2: Validate fields per type

   { search { ... on User { name } ... on Post { title } ... on Comment { content } } } queries name on User, title on Post, and content on Comment correctly. Other options either query fields directly without fragments or use wrong fields.

3. Final Answer:

   { search { ... on User { name } ... on Post { title } ... on Comment { content } } } -> Option A

4. Quick Check:

   Use inline fragments per type to query union fields [OK]

Hint: Use one inline fragment per union type with correct fields [OK]

Common Mistakes:

• Querying all fields directly without fragments
• Using wrong fields for a type
• Mixing fields inside fragments incorrectly