How to use GraphQL aliases

In this article we will go through the concept of aliases and how you can benefit from this simple feature of the GraphQL language.


To understand the concept of aliases in GraphQL we need to take a closer look at general query logic and identify what each part of a query is responsible for. All examples in this article can be found in this GitHub repository. If you also want to try these examples out in the GraphiQL tool, just clone the repository with

git clone -b feature/4-graphql-aliases

and then follow the readme, start the server and move to /graphiql.

Checkout the upcoming free GraphQL language course with in browser exercices
From upcoming GraphQL Language course

To illustrate the aliases concept, let’s take this query for retrieving users from the database.

This query consists of different parts

  • operation type (query): the type of action we want to do with the query. In GraphQL specification we have three different operation types -query, mutation and subscription.
  • name(getUsers): name is important for debugging purposes.
  • selection set (id, firstName, lastName, phone, username): this defines what data we would like to retrieve from the server.

There are also parts of the query which are called arguments, variables, fragments and directives. For simplicity’s sake we should leave that alone for now and return to them in future articles. When we execute this query with the proper server setup (check out Github repository), we should be able to retrieve the data.

You can see that the data are contained in the users field, which refers to the selected field in the query.

Why aliases?

However, what happens if we want to query the users based on some argument? Let’s say that we have a schema for users, where the role argument is implemented and we want to query the users based on that role argument. Role arguments are used as a filter to retrieve the users. At first glance, the query can look like this:

However, this will return an error, because different data are stored in the same selection field. All results cannot be stored, as they have the same name and will be overwritten. For example, graphql-js will throw the error like this:

To resolve this issue we can use the aliases. The same query can be then rewritten with aliases like this

By executing this query we will retrieve the data filtered by the argument in the following format:


You can see that it is a much cleaner way to retrieve the data. We do not have to filter it on the frontend and have it prefiltered in the apollo store right away. This is not the best option, but it should be considered. When you use aliases, it is extremely important to keep in mind the performance and use of the data loader for batching requests to the database. Also it is appropriate in this case to use persisted queries, as the query is a bit bigger in size. This can be reduced with fragments. Tweaking GraphQL performance will be the topic of the next few articles so be sure to subscribe. To dive deeper into performance, you can also check out the article on writing high performance web with React 16, Next.js and Node.js 8.x.

Did you like this post? Then clap for this article as it makes it easier for others to find it. The repository with the examples and project setup can be cloned from this GitHub branch. You can get early access to upcoming free GraphQL course by subscribing at