Skip to main content

​
Overview

Union types represent an object that could be one of a list of GraphQL object types. Unlike interfaces, unions don’t define shared fields. Inherits from: Rails::GraphQL::Type Specification: GraphQL Union Type Definition

​
Class Attributes

​
members
Array<Object>
Collection of object types that are members of this union
​
VALID_MEMBER_TYPES
Array<Class>
default:"[Type::Object]"
The list of accepted classes for union members (only Object types)

​
Class Methods

​
append(*others)

Add one or more object types as members of the union.
​
others
Array<Object>
required
Object types to add to the union. Can be classes or symbols (type names)
class SearchResultUnion < GraphQL::UnionType
  append UserType, PostType, CommentType
  
  # Or using symbols
  append :user_type, :post_type
end

​
type_for(value, *)

Determine which member type is compatible with the provided value.
​
value
Any
required
The value to find a type for
​
return
Object | nil
Returns the first compatible member type, or nil if none found
SearchResultUnion.type_for(user_instance) # => UserType
SearchResultUnion.type_for(post_instance) # => PostType

​
of_kind

Return the base type of objects in this union.
​
return
Class
The base type class shared by all union members
SearchResultUnion.of_kind # => ActiveRecord::Base (example)

​
=~(other)

Check if another type is equivalent to this union.
​
other
Type
required
The type to compare
​
return
Boolean
Returns true if the other type is equivalent to any union member

​
validate!(*)

Validate the union definition. 
class EmptyUnion < GraphQL::UnionType
  # No members defined
end

EmptyUnion.validate!
# => ArgumentError: A union must contain at least one member.

​
Included Modules

​
Helpers::Instantiable
Provides instance creation capabilities

​
Configuration

class SearchResultUnion < GraphQL::UnionType
  description "Possible search result types"
  
  append UserType, PostType, CommentType
end

​
Usage Examples

​
Basic Union

class MediaUnion < GraphQL::UnionType
  append ImageType, VideoType, DocumentType
end

field :media_items, [MediaUnion] do
  resolve ->(obj, args, ctx) {
    # Return mix of Image, Video, and Document objects
    obj.media_attachments
  }
end

​
Dynamic Member Addition

class NotificationUnion < GraphQL::UnionType
  append MessageNotificationType
  append LikeNotificationType
end

# Later, add more types
NotificationUnion.append FollowNotificationType

​
Union with Symbol References

class ActivityUnion < GraphQL::UnionType
  # Reference types by symbol (must be registered in type map)
  append :comment_activity_type, :like_activity_type
end

​
Type Resolution

When GraphQL needs to determine which member type a value belongs to, it calls type_for(value). Ensure each member type implements valid_member?(value) correctly: 
class UserType < GraphQL::ObjectType
  self.assigned_to = User
  
  # valid_member? automatically checks if value is a User instance
end

class PostType < GraphQL::ObjectType
  self.assigned_to = Post
  
  # valid_member? automatically checks if value is a Post instance
end

​
Special Features

​
Base Class Enforcement

All union members must share the same base class. This ensures consistent behavior when resolving union types: 
# Valid - all inherit from ActiveRecord::Base
append UserType, PostType, CommentType

# Invalid - mixing different base classes
append UserType, SomeOtherBaseType  # ArgumentError!

​
Inspection

Unions provide detailed inspection output: 
SearchResultUnion.inspect
# => "#<GraphQL::Union SearchResult (3) {User | Post | Comment}>"
  • Object - Define union member types
  • Interface - Alternative for polymorphism with shared fields

Build docs developers (and LLMs) love

Get started for freeTalk to us