When working with a GraphQL API, you may want to rename a field to something other than what the API has to offer. Aliases exist as part of the GraphQL spec to solve this exact problem.

Aliases allow you to rename a single field to whatever you want it to be. They are defined client-side, so you don’t need to update your API to use them.

Imagine requesting data using the following query from an API:

GraphQL 

query GetEntries {
  entries {
    id
    updated_at
  }
}

You will get the following JSON response:

JSON 

{
  "entries": [
    {
      "id": "4fe43afe",
      "updated_at": "2020-07-05T22:56:15.012Z"
    }
  ]
}

The id here is fine, but the updated_at doesn’t quite conform to the camel case convention in JavaScript. Let’s change it by using an alias.

GraphQL 

query GetEntries {
  entries {
    id
    updatedAt: updated_at
  }
}

Which yields the following:

JSON 

{
  "entries": [
    {
      "id": "4fe43afe",
      "updatedAt": "2020-07-05T22:56:15.012Z"
    }
  ]
}

Creating an alias in GraphQL is easy. Simply add a colon and new name next to the field you want to rename.

Aliasing fields with arguments

The examples above only cover fields that don’t have any arguments. When creating an alias on a field that contains arguments, the syntax is slightly different. Instead of the alias appearing to the right of the field, it’s placed on the left.

Take a look at the following example. It contains the updated_at field, but again, we want to rename it.

GraphQL 

query GetEntries {
  entries {
    id
    updated_at(format: "MM dd, YYYY")
  }
}

Now with an alias:

GraphQL 

query GetEntries {
  entries {
    id
    updatedAt: updated_at(format: "MM dd, YYYY")
  }
}

And the result:

JSON 

{
  "entries": [
    {
      "id": "4fe43afe",
      "updatedAt": "July 5, 2020"
    }
  ]
}

Requesting a single field more than once

What’s great about aliases is you can request the same field several times and get different results. Take a look at this example:

GraphQL 

query GetEntries {
  entries {
    id
    updated_at
    updated_at(format: "MM dd, YYYY")
  }
}

Running this query would yield an error because two of the field names are the same. You can use an alias here to avoid the error.

GraphQL 

query GetEntries {
  entries {
    id
    updatedAt: updated_at
    updatedAtHumanized: updated_at(format: "MM dd, YYYY")
  }
}

Running the updated query would give us the results we’re expecting.

JSON 

{
  "entries": [
    {
      "id": "4fe43afe",
      "updatedAt": "2020-07-05T22:56:15.012Z",
      "updatedAtHumanized": "July 5, 2020"
    }
  ]
}