Unions and interfaces

Unions and interfaces are abstract GraphQL types that enable a schema field to return one of multiple object types.

Union type

When you define a union type, you declare which object types are included in the union:

1
union Media = Book | Movie

A field can have a union as its return type. In this case, it can return any object type that's included in the union:

1
type Query {
2
  allMedia: [Media] # This list can include both Books and Movies
3
}

All of a union's included types must be object types (not scalars, input types, etc.). Included types do not need to share any fields.

Example

The following schema defines a Result union type that can return either a Book or an Author:

1
union Result = Book | Author
2

3
type Book {
4
  title: String
5
}
6

7
type Author {
8
  name: String
9
}
10

11
type Query {
12
  search(contains: String): [Result]
13
}

The Result union enables Query.search to return a list that includes both Books and Authors.

Querying a union

GraphQL clients don't know which object type a field will return if the field's return type is a union. To account for this, a query can include the subfields of multiple possible types.

Here's a valid query for the schema above:

1
query GetSearchResults {
2
  search(contains: "Shakespeare") {
3
    ... on Book {
4
      title
5
    }
6
    ... on Author {
7
      name
8
    }
9
  }
10
}

This query uses inline fragments to fetch a Result's title (if it's a Book) or its name (if it's an Author).

For more information, see Using fragments with unions and interfaces.

Resolving a union

To fully resolve a union, Apollo Server needs to specify which of the union's types is being returned. To achieve this, you define a __resolveType function for the union in your resolver map.

The __resolveType function uses a returned object's fields to determine its type. It then returns the name of that type as a string.

Here's an example __resolveType function for the Result union defined above:

1
const resolvers = {
2
  Result: {
3
    __resolveType(obj, context, info){
4
      if(obj.name){
5
        return 'Author';
6
      }
7
      if(obj.title){
8
        return 'Book';
9
      }
10
      return null; // GraphQLError is thrown
11
    },
12
  },
13
  Query: {
14
    search: () => { ... }
15
  },
16
};
17

18
const server = new ApolloServer({
19
  typeDefs,
20
  resolvers,
21
});
22

23
server.listen().then(({ url }) => {
24
  console.log(`🚀 Server ready at ${url}`)
25
});

Interface type

An interface specifies a set of fields that multiple object types can include:

1
interface Book {
2
  title: String
3
  author: Author
4
}

If an object type implements an interface, it must include all of that interface's fields:

1
type Textbook implements Book {
2
  title: String # Must be present
3
  author: Author # Must be present
4
  courses: [Course]
5
}

A field can have an interface as its return type. In this case, it can return any object type that implements that interface:

1
type Query {
2
  schoolBooks: [Book] # Can include Textbooks
3
}

Example

The following schema defines a Book interface, along with two object types that implement it:

1
interface Book {
2
  title: String
3
  author: Author
4
}
5

6
type Textbook implements Book {
7
  title: String
8
  author: Author
9
  courses: [Course]
10
}
11

12
type ColoringBook implements Book {
13
  title: String
14
  author: Author
15
  colors: [Color]
16
}
17

18
type Query {
19
  schoolBooks: [Book]
20
}

In this schema, Query.schoolBooks returns a list that can include both Textbooks and ColoringBooks.

Querying an interface

If a field's return type is an interface, clients can query that field for any subfields included in the interface:

1
query GetBooks {
2
  schoolBooks {
3
    title
4
    author
5
  }
6
}

Clients can also query for subfields that aren't included in the interface:

1
query GetBooks {
2
  schoolBooks {
3
    title # Always present (part of Book interface)
4
    ... on Textbook {
5
      courses { # Only present in Textbook
6
        name
7
      }
8
    }
9
    ... on ColoringBook {
10
      colors { # Only present in ColoringBook
11
        name
12
      }
13
    }
14
  }
15
}

This query uses inline fragments to fetch a Book's courses (if it's a Textbook) or its colors (if it's a ColoringBook).

For more information, see Using fragments with unions and interfaces.

Resolving an interface

As with union types, Apollo Server requires interfaces to define a __resolveType function to determine which implementing object type is being returned.

Here's an example __resolveType function for the Book interface defined above:

1
const resolvers = {
2
  Book: {
3
    __resolveType(book, context, info){
4
      if(book.courses){
5
        return 'Textbook';
6
      }
7
      if(book.colors){
8
        return 'ColoringBook';
9
      }
10
      return null; // GraphQLError is thrown
11
    },
12
  },
13
  Query: {
14
    schoolBooks: () => { ... }
15
  },
16
};