Combining GraphQL multiple queries to boost performance

GraphQL allows developers to request only the data they need in a single, efficient query. Combining multiple GraphQL queries into one will reduce network requests and boost performance.

In this article, we’ll cover different ways to combine multiple GraphQL queries into a single request, best practices for joining GraphQL queries, and how to combine multiple GraphQL queries from different APIs.

If you’re new to GraphQL, you can check out our introduction in What is GraphQL?

In this tutorial, we will look at the Star Wars GraphQL API as an introduction to making lightspeed queries for your application.

What does it mean to combine multiple GraphQL queries?

Combining multiple GraphQL queries means grouping multiple separate GraphQL queries into a single network request. The purpose of this is to improve performance (by just having one very specific combined query).

The ability to combine multiple queries makes GraphQL much faster than REST APIs, which accounts for its growing popularity. With REST API endpoints, your client code is forced to request each data entity separately and tie them together for its own purposes. In contrast, with GraphQL, you can (and should) fetch all the data you need in a single API request. GraphQL provides the ability for the client to request that the back end filter down and aggregate the data into a useful, cohesive chunk and return it as one response.

There are multiple ways to achieve this, and there are some best practices you should be aware of that will help improve performance. You’ll find combining GraphQL queries to be a very powerful performance enhancement that makes developing client-side logic much neater.

Benefits of combining multiple GraphQL queries

• Optimize your API requests and improve performance. Combining multiple queries into one reduces the number of API calls, reducing network latency and improving speed. These combined queries help to shift the bulk of the work to the server where data layer optimizations are best implemented.

• Boost developer productivity. Combining multiple GraphQL queries allows you to simplify your code base by avoiding boilerplate and writing queries specific to your interface needs. Because of the dynamic nature of the GraphQL request, you can query only the information your UI needs and avoid aggregating multiple API responses on the client side. This reduces processing of post-API call data, and therefore complexity, in the UI.

• Simplified client logic. Dealing with just one GraphQL API response is much easier than handling multiple asynchronous responses. This simplifies your client-side code and reduces the likelihood of bugs being introduced.

How to combine multiple GraphQL queries

To show you how easy it is to combine multiple GraphQL queries in a single request, we’ll show you some practical examples of GraphQL requests that you can run against a real API. For this, you'll use an interactive GraphQL API explorer for a Star Wars API. No setup or API keys are needed — you can simply paste in a query and get an immediate API response.

Let's start with a simple example just to show you how to use the explorer: Open the Star Wars API explorer and paste in the following query to request all the starships.

Screenshot of a query and response from the Star Wars API.

You can see in the response that each starship has an ID. We'll be making use of these in later examples when we query for a single item. For example, the query below returns a single starship, the Death Star.

Now, imagine you wanted to fetch data for your web page that displays information about multiple different data types — a lead character (or “person”), a starship, and a planet in the Star Wars universe.

If you're used to dealing with RESTful APIs, you might be tempted to write the following GraphQL requests to receive the three pieces of data you need:

Although these requests would return all the data you need, you'd be missing out on the speed and efficiency that GraphQL is known for, because the three queries must get executed separately. Instead, you can combine them into one request:

Combining GraphQL queries of the same type

This is the most common way to join multiple GraphQL queries together. However, what if you needed to combine multiple GraphQL queries that are the same type? 

For example, you might need to compare some data about two different people. As you'd expect, separate queries (as below) is not the most efficient way to fetch the data.

However, if you combine them in the standard way, the GraphQL API won't accept querying the same object twice and will throw an error.

The solution to this problem is using aliases. Aliases allow you to rename fields with the same name, avoiding the naming conflict. Below, luke, leia and han are examples of aliases.

Screenshot of an aliased query

Best practices when combining GraphQL queries

Use interfaces to query types that share common fields

Interfaces are something that can only be used if they've been created on the server side by the GraphQL API developer. If you have control over the API yourself, you can create them, but if you're consuming a third-party API, you'll need to check whether there are any interfaces available in the schema by running a GraphQL introspection query on the API. 

Luckily for us, the Star Wars API has an interface called Node, which we can discover by running this introspection query:

This query returns the entire schema of the API, part of which includes the definition of the Node interface:

An interface in GraphQL defines a set of common fields that each of the possible types must implement. In the case of Node, the only shared field is name. 

Because the Node interface exists, the user of this API can query multiple types in a single query. For example, if you wanted a web page that dealt with the different kinds of Star Wars transportation, you could use the Node interface to query across starships and vehicles at the same time, covering all the different types of transport.

Use unions to query types with no common fields

Use unions instead of interfaces if you want to group completely different types with no shared fields or common structure. Just like interfaces, unions are something you can only use if the API has created them. 

Our Star Wars API doesn't have any unions defined, so for this next example, we'll be using the GitHub API Explorer. This tool requires you to have a GitHub account and a personal access token set up if you want to run the queries directly in the explorer. However, we'll also be providing screenshots of our queries and responses so you can follow along without having to set this up.

Running the same introspection query on the GitHub API shows a union called IssueOrPullRequest:

Screenshot of an introspection query to the GitHub GraphQL explorer, which returns a union called IssueOrPullRequest.

To make use of this union type, run the following query against the octocat/Hello-World public repository, which happens to return a pull request. Changing the number to 41, however, returns a Git issue, which shows how the union type can be used to query different types in the same request. Unions such as these can be used even when no shared fields exist between the different types.

Use GraphQL fragments to make a query more readable

A fragment is a reusable piece of query logic. It makes your code more modular and readable. If you are returning the same properties of a type in different parts of your query, you can package them up in a fragment and simply reuse the name of the fragment where needed. This can save time and make your request code much more readable.

Let’s take our earlier example of querying the three key people of Star Wars:

Notice that we don’t really need to be stating the name, birthYear and hairColor properties for each person. We can aggregate these into a fragment and use that.

With much more complex types, this can save a lot of eye strain. It also allows you to keep all the properties in a single place, making maintenance of returned properties simpler.

What about combining GraphQL queries from different APIs?

If you manage multiple different GraphQL APIs, combining them into a single integrated API makes querying them simpler for your customers. It allows them to query related data together in one query, even if it's stored separately. Depending on the complexity of your system, you can choose between these three different options:

• Schema stitching: This is a technique done on the server side where you query two different GraphQL APIs to find out the schema of each and then stitch them together, producing a new unified GraphQL API. When a client queries your new GraphQL API, your backend code figures out which queries need to be sent to the original two APIs. It then performs the queries, combines the responses, and returns a single response to the client. Schema stitching is simple to implement and gives a unified query interface for your client, but it is a fairly manual approach, and it requires one team to take control of the unified interface. Hence, it is better suited for smaller systems.

• Federated GraphQL: This approach is better suited for larger, distributed systems such as microservices. Each service controls its own schema but can reference entities from other services. Federated GraphQL involves a federated gateway that aggregates and composes the schemas from all services into one unified schema. 

• API aggregation: This uses an API gateway (such as Kong) to combine the data from different GraphQL endpoints. It's less scalable than the other two approaches, and the code is more tightly coupled to each API, but it's the only way to combine a GraphQL API with another type of API such as REST.

Using GraphQL for content management 

GraphQL is designed to allow multiple queries out of the box, and it has many built-in features that help improve performance, UX, and developer experience. GraphQL is also ideal if you have multiple nested content models that need to be fetched flexibly or reused for content across multiple platforms — for example, in content management.

Contentful provides a robust GraphQL API for content management that allows you to flexibly query your content, supports nested relationships, and offers features like filtering, pagination, and the ability to preview draft content.

Start building

Sign up for a free Contentful account

Use your favorite tech stack, language, and framework of your choice.

Subscribe for updates

Build better digital experiences with Contentful updates direct to your inbox.