How to use Union Type in GraphQL?

In GraphQL, a union type is a type that represents a combination of multiple other types. It allows you to return different types of data from a single field in your GraphQL schema.

For example, let’s say you have a schema with a field called “search” that returns a list of results.

The results can be either a list of users, a list of books, or a list of movies. In this case, you can define a union type that combines the “user” type, the “book” type, and the “movie” type. The “search” field can then return any of these types as part of the results.

Union types are useful in cases where you have a field that can return multiple different types of data. They allow you to define a single field that can handle multiple types, which can make your schema more flexible and easier to work with.

Get in details

Here is an example of how you might use a union type in a GraphQL schema:

type User {
  id: ID!
  name: String!
  email: String!
}

type Book {
  id: ID!
  title: String!
  author: String!
}

type Movie {
  id: ID!
  title: String!
  director: String!
}

union Result = User | Book | Movie

type Query {
  search(query: String!): [Result]
}

In this example, we define three different types: User, Book, and Movie. We then define a union type called Result that combines these three types. Finally, we define a field called search that accepts a query parameter and returns a list of Results.

Now, when someone queries the search field, they can get a list of results that can be either Users, Books, or Movies. This allows the search field to return different types of data depending on the query.

Here is an example query that uses the search field:

query {
  search(query: "The Matrix") {
    __typename
    ... on User {
      id
      name
      email
    }
    ... on Book {
      id
      title
      author
    }
    ... on Movie {
      id
      title
      director
    }
  }
}

In this query, we use the search field to search for the term “The Matrix”. Because the search field returns a list of Results, we use the __typename field and the ... on syntax to specify which fields we want to retrieve for each type. In this case, we retrieve the id, name, and email fields for Users, the id, title, and author fields for Books, and the id, title, and director fields for Movies.

This is just a simple example, but it shows how you can use union types to return different types of data from a single field in your GraphQL schema.

How about Union Input in GraphQL?

To set a union type as an input in a GraphQL schema, you would define the union type in the same way that you would define it as a return type, using the union keyword followed by the name of the union and the different object types that it can represent.

Then, you would use the union type as the type for the input argument in your GraphQL schema.

Here is an example of how you might define a union type called SearchInput that can represent either a UserInput or a PageInput object, and then use it as the type for an input argument called input in a search field:

union SearchInput = UserInput | PageInput

type Query {
  search(input: SearchInput): SearchResult
}

In this example, the SearchInput union type is defined and then used as the type for the input argument in the search field.

This allows the search field to accept either a UserInput or a PageInput object as input. You can then use the input argument in the search field to specify which object type you want to search for.

For example, you might use the following query to search for a user with a specific username:

query {
  search(input: {
    __typename: "UserInput",
    username: "openai"
  }) {
    __typename
    ... on User {
      username
      name
      profileImageUrl
    }
  }
}

In this query, the search field is provided with an input argument that specifies that it should search for a UserInput object with the username openai.

The __typename field is used to specify the object type that the input argument should be interpreted as. The query then uses the ... on User syntax to specify which fields should be returned for the User object type.

Be Caution!!!

itt depends on the specific use case. Input unions can be useful in situations where you want to allow multiple different input types to be used in the same argument.

For example, if you have an argument that can accept either a string or a number, you can use an input union to define the valid input types. This can make your GraphQL schema more flexible and reusable.

However, input unions can also make your schema more complex and difficult to understand, so it’s important to consider whether they are necessary for your specific use case.

If you only need to accept a single input type for a given argument, it may be simpler to just use that input type directly.