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.

David Mráz
Mar 14, 2018 · 3 min read


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

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

Checkout the upcoming free GraphQL language course with in browser exercices

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


Everything you need to know about building AI products.

David Mráz

Written by

Founder of Atheros | Artificial Intelligence | Machine Learning | JavaScript, Python, C++ | Business



Everything you need to know about building AI products.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade