Union types in GraphQL

Introduction

Union types let you combine different object types into one. This helps when a field can return different kinds of data.

When a query can return different types of objects, like a search returning books or authors.

When you want to handle multiple related types in one response.

When you need to simplify your schema by grouping types that share no common fields.

When you want to write flexible queries that adapt to different data shapes.

Syntax

GraphQL

union SearchResult = Book | Author | Magazine

Union types list multiple object types separated by | (pipe).

Each type in the union must be an object type, not a scalar or interface.

Examples

This union type groups Photo and Video types under Media.

GraphQL

union Media = Photo | Video

SearchResult can be a User, a Post, or a Comment.

GraphQL

union SearchResult = User | Post | Comment

Sample Program

This example defines a union SearchResult that can be a Book or an Author. The query searches and handles both types separately.

GraphQL

type Book {
  title: String
  author: String
}

type Author {
  name: String
  books: [Book]
}

union SearchResult = Book | Author

# Query example
query {
  search(keyword: "GraphQL") {
    ... on Book {
      title
      author
    }
    ... on Author {
      name
    }
  }
}

Important Notes

When querying a union type, use inline fragments (... on TypeName) to access fields of each type.

Union types cannot have fields themselves; only the member types have fields.

Summary

Union types group multiple object types into one.

Use unions when a field can return different object types.

Query unions with inline fragments to get data from each type.

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