How to Use GraphQL Aliases

Aliases are an essential GraphQL feature. It helps you to avoid unnecessary API calls and dramatically improve data fetching performance in your app or integration.

What are aliases?

In a nutshell, aliases are a feature that allows you to rename the fields returned by a query or mutation.

Aliases are helpful when you wish to return the same field multiple times based on different arguments and in a single API call.

If you're not yet familiar with the fundamentals of GraphQL, visit the Learn GraphQL guides before continuing.

Using aliases: requesting multiple orders in one query

Imagine you wish to use the query orderById to retrieve data about two different orders in a single API call. How would you do that? If you don't know about aliases, you'd probably form your query this way:

query {
  orderById(id: "c6cdba3f-1220-44c3-aadc-eeec0f9eb1aa") {
    total
  }
  
  orderById(id: "20de7a12-9f2d-4e84-9f1c-21003b00ea63") {
    total
  }
}

But the query above is not well-formed and does not pass schema validation. The GraphQL server would return an error object that might look like this:

{
  "error": {
    "errors": [
      {
        "message": "Fields \"orderById\" conflict because they have differing arguments. Use different aliases on the fields to fetch both if this was intentional.",
        "locations": [
          {
            "line": 2,
            "column": 3
          },
          {
            "line": 5,
            "column": 3
          }
        ]
      }
    ]
  }
}

The most important field is message. It says:

Fields "orderById" conflict because they have differing arguments. Use different aliases on the fields to fetch both if this was intentional.

The cause of the conflict is simple: an object can not have properties with the same name.

In order to resolve the conflict, we must rename at least one of the repeated orderById fields. For this, we'll use aliases:

query {
  orderOne: orderById(id: "c6cdba3f-1220-44c3-aadc-eeec0f9eb1aa") {
    total
  }
  
  orderTwo: orderById(id: "20de7a12-9f2d-4e84-9f1c-21003b00ea63") {
    total
  }
}

To rename a field using aliases, we must write newFieldName: and then the actual field's name in the schema. In the example above, we're renaming the first orderById field to orderOne, and the second one to orderTwo. We're still requesting the same field, but we're telling GraphQL that we want to retrieve it with a different name to avoid conflicts.

Now that our query is well-formed and passes the schema validation, here is a response we might get back:

{
  "data": {
    "orderOne": {
      "total": 12.09
    },
    "orderTwo": {
    "total": 33.55
    }
  }
}

Note how the two orderById fields included in the query were renamed to orderOne and orderTwo.

With aliases, you no longer need to make multiple API calls to get the data you need. Instead, you can get all data you want in a single call. That makes data fetching on the client more efficient and productive.

By using aliases, you can prevent collisions on field names and ask for the same field as many times as you want. They're an essential feature when working with GraphQL at scale.

What's next?

Aliases are frequently used in combination with another cool GraphQL feature called fragments, so now it's a good idea to learn how to use GraphQL fragments.