Unions

A union type is a type that may be any of a list of possible objects.

GraphQL Spec

Read about unions.

A union is a type defined in terms of different objects:

{:unions
 {:SearchResult
  {:members [:Person :Photo]}}

 :objects
 {:Person
  {:fields {:name {:type String}
            :age {:type Int}}}

  :Photo
  {:fields {:imageURL {:type String}
            :title {:type String}
            :height {:type Int}
            :width {:type Int}}}

  :Query
  {:fields
   {:search
    {:type (list :SearchResult)
     :args {:term String}}}}}}

A union definition must include a :members key, a sequence of object types.

The above example identifies the SearchResult` union type to be either a ``Person (with fields name and age), or a Photo (with fields imageURL, title, height, and width).

Unions must define at least one type; each member type must be an object type (members may not be reference scalar types, interfaces, or other unions).

When a client makes a union request, they must use the fragment spread syntax to identify what is to be returned based on the runtime type of object:

{ search (term:"ewok") {
  ... on Person { name }
  ... on Photo { imageURL title }
}}

This breaks down what will be returned in the result map based on the type of the value produced by the search query. Sometimes there will be a name key in the result, and other times an image-url and title key. This may vary result by result even within a single request:

{:data
 {:search
  [{:name "Nik-Nik"}
   {:imageURL "http://www.telegraph.co.uk/content/dam/film/ewok-xlarge.jpg"
    :title "an Ewok in The Return of the Jedi"}
   ]}}

Tip

When a field or operation type is a union, the field resolver may return any of a number of different concrete object types, and Lacinia has no way to determine which; this information must be explicitly provided.