Union Types in GraphQL Schema
GraphQL is an open-source Query Language for APIs that allows us to query only the data we require, unlike the REST framework which returns the entire data as is configured in its API. With GraphQL, we can maintain a Schema that defines what data we can query from the server, and we can define a proper contractual schema like this between the client and the server. In this article, we will learn about the Union Types in GraphQL Schema, and implement our resolver for it in Node.JS.
Union Types in GraphQL Schema
Union type in a GraphQL Schema is declared using the union keyword and the pipe symbol (|), and it suggests that a field can have more than one type. Let’s take a look at the example below –
type Post {
text: String!
title: String!
}
type Author {
name: String!
}
union Feed = Post | Author
Here, Feed is a union type of Post and Author, implying that Feed can be either of type Post or of type Author.
Now, let’s create a basic Schema with a union type, and create our own resolver to see it in action.
Using Union Types in Queries
Step 1: Define the Schema
- To define the GraphQL schema, Create a file and save it with .graphql extension.
- For example we can name the file as schema.graphql.
Javascript
const typeDefs = ` type Book { title: String! isbn: String! } type Author { name: String! books: [Book!]! } union SearchResult = Book | Author type Query { search(query: String!): [SearchResult] } `; module.exports = { typeDefs, }; |
Step 2: Implement Resolvers
Let’s set up the server, save the file as server.js and we will implement resolvers. Resolver functions are responsible for resolving the queries that are defined in the schema. Here, we will create a “search” resolver that will be responsible for resolving the “search” query, and we will return a static data based on the provided query string. We will also create a “SearchResult” resolver that will determine the type of the search result, which will be either “Book” or “Author”.
Then, we will create an executable schema using the “makeExecutableSchema” function that will combine our schema and resolvers, and create an executable GraphQL schema.
At last, we will create and initialise our App using express, and start the app.
Javascript
const express = require( 'express' ); const { graphqlHTTP } = require( 'express-graphql' ); const { makeExecutableSchema } = require( 'graphql-tools' ); const { typeDefs } = require( './schema.graphql' ); // Define the resolver const resolvers = { Query: { search: (_, { query }) => { if (query.toLowerCase().includes( 'graphql' )) { return [ { __typename: 'Book' , title: 'GraphQL in Action' , isbn: '1234567890' }, { __typename: 'Author' , name: 'John Doe' , books: [] }, ]; } else { return []; } }, }, SearchResult: { __resolveType: (obj) => { if (obj.title && obj.isbn) { return 'Book' ; } else if (obj.name && obj.books) { return 'Author' ; } return null ; }, }, }; // Create the executable schema const schema = makeExecutableSchema({ typeDefs, resolvers }); // Create the express app const app = express(); // Enable CORS for all routes app.use((req, res, next) => { res.header( 'Access-Control-Allow-Origin' , '*' ); res.header( 'Access-Control-Allow-Headers' , 'Content-Type' ); res.header( 'Access-Control-Allow-Methods' , 'OPTIONS,POST' ); next(); }); // Set up the GraphQL endpoint app.use( '/graphql' , graphqlHTTP({ schema, graphiql: true , // Enable GraphiQL for testing in the browser }) ); // Start the server const PORT = process.env.PORT || 3000; app.listen(PORT, () => { console.log(`Server running on http: //localhost:${PORT}/graphql`); }); |
Step 3: Start the server
To start the server run the below command in the terminal.
node server.js
Output:
Server running on http://localhost:3000/graphql
Step 4: Test the Query in GraphiQL Interface
To test the query, execute the below query in the GraphiQL interface.
query {
search(query: "GraphQL") {
__typename
... on Book {
title
isbn
}
... on Author {
name
books {
title
isbn
}
}
}
}
In the above query, we first define a search query that takes in a parameter with value, “GraphQL”, and since it can return data with the type of either Book, or Author, so we define 2 cases, first if the type is Book, we select only the title and the isbn field from the response, and if the type is Author, we select only title and books of type title, and isbn.
Output:
The output of the above query will look like below
Conclusion
In this article, we learned about the Union types in GraphQL Schema, and how we use it provide more than one type to a data field. We also created a Node.JS server, with a GraphQL schema, and a resolver for it to see it in action. Union is a powerful type that can help us handle different types of data in different conditions.
Contact Us