Union vs Interface in GraphQL: Key Differences and Usage

In GraphQL, a union type allows a field to return one of several object types without shared fields, while an interface defines a set of common fields that multiple types must implement. Use union when types differ completely, and interface when types share common fields.

Quick Comparison

This table summarizes the main differences between union and interface in GraphQL.

Aspect	Union	Interface
Purpose	Represents multiple types without shared fields	Defines common fields for multiple types
Field Sharing	No shared fields required	Must have shared fields defined in interface
Type Usage	Used for fields returning different object types	Used for polymorphism with common fields
Implementation	Types do not implement union explicitly	Types must implement the interface explicitly
Querying	No guaranteed common fields in query	Can query common fields directly
Example Use Case	Search results returning different types	Entities sharing common properties

Key Differences

A union type in GraphQL is a way to say a field can return one of several different object types, but these types do not need to share any fields. This means you cannot query any common fields directly on the union without specifying the exact type using inline fragments.

On the other hand, an interface defines a set of fields that all implementing types must have. This allows clients to query those common fields directly on the interface type without knowing the exact implementing type. Each type that implements the interface must explicitly declare it and provide the fields defined by the interface.

In summary, use union when the types are unrelated and do not share fields, and use interface when you want to enforce a common structure across multiple types and allow querying shared fields easily.

Code Comparison

Here is an example of a union type used to represent a search result that can be either a Photo or a User.

graphql

union SearchResult = Photo | User

type Photo {
  id: ID!
  url: String!
}

type User {
  id: ID!
  username: String!
}

type Query {
  search(text: String!): [SearchResult!]!
}

Output

Query 'search' returns a list of either Photo or User objects, but no common fields guaranteed.

Interface Equivalent

Here is how you can use an interface to define common fields for types like Photo and User that share an id field.

graphql

interface Node {
  id: ID!
}

type Photo implements Node {
  id: ID!
  url: String!
}

type User implements Node {
  id: ID!
  username: String!
}

type Query {
  nodes: [Node!]!
}

Output

Query 'nodes' returns a list of objects implementing Node interface, each having an 'id' field.

When to Use Which

Choose union when your field can return multiple types that do not share any common fields, such as different kinds of search results or notifications. This is useful when the types are completely distinct.

Choose interface when you want to enforce a common set of fields across multiple types and allow clients to query those fields directly, such as entities with an id or name. This supports polymorphism with shared structure.

Key Takeaways

Use union for fields returning multiple unrelated types without shared fields.

Use interface to define common fields that multiple types must implement.

Interfaces allow querying shared fields directly, unions require inline fragments.

Types must explicitly implement interfaces but not unions.

Choose based on whether your types share structure or are completely different.