Union types
Union types are similar to interfaces however, while interfaces dictate fields that must be common to all implementations, unions do not. Unions only represent a selection of allowed types and make no requirements on those types. Hereβs a union, expressed in GraphQL Schema Definition Language (SDL):
Whenever we return a MediaItem
in our schema, we might get an Audio
, a
Video
or an Image
. Note that members of a union type need to be concrete
object types; you cannot create a union type out of interfaces, other unions or
scalars.
A good use case for unions would be on a search field. For example:
Here, the searchMedia
field returns [MediaItem!]!
, a list where each member
is part of the MediaItem
union. So, for each member, we want to select
different fields depending on which kind of object that member is. We can do
that by using
inline fragments .
Defining unions
In Strawberry there are two ways to define a union:
You can use the Union
type from the typing
module which will autogenerate
the type name from the names of the union members:
Or if you need to specify a name or a description for a union you can use
Annotated with the strawberry.union
function:
Resolving a union
When a fieldβs return type is a union, GraphQL needs to know what specific
object type to use for the return value. In the example above, each MediaItem
must be categorized as an Audio
, Image
or Video
type. To do this you need
to always return an instance of an object type from your resolver:
Single member union
Sometimes you might want to define a union with only one member. This is useful for future proofing your schema, for example if you want to add more types to the union in the future.
Python's typing.Union
does not really support this use case, but using
Annotated and strawberry.union
you can tell Strawberry that you want to define
a union with only one member: