Customising and Aliasing GraphQL Fields with Hasura

We recently released a new version of Hasura which adds support for customising names of root fields and column fields. It is important to distinguish what it means to customise names of fields at the server and GraphQL aliasing at client side.

Client Side Aliasing with GraphQL Aliases

GraphQL Aliases let you rename the result of a field to anything you want. Consider the table users with fields id, full_name, email_addr, created_at and updated_at. Let's look at the anatomy of a simple query to understand this better. For example:

query getUsers {
  users {
    id
    full_name
    email_addr
  }
}

There are 3 parts to the above query:

• operation type - query
• operation name - getUsers
• selection set - id, full_name, email_addr

The response structure of the above query would look like:

{
  "data": {
    "users": [
      {
        "id": "3ea1352a-6654-444d-9357-62816ccbd2b3",
        "full_name": "Praveen",
        "email_addr": "email@mydomain.com"
      }
    ]
  }
}

Now let's say, you want to map the response fields to UI elements directly and not deal with any transformations on the frontend. Ideally you would like the response from server to come in that format to achieve this. This can be done with GraphQL Aliases. You can alias the selection set to names of your choice.

We most likely want to replace verbose or vague fields with simple and readable fields for the UI.

Now the query can be written like below and the response format will match the keys you intended to be.

# Query
query {
  users {
    id
    name: full_name
    email: email_addr
  }
}

# Response
{
  "data": {
    "users": [
      {
        "id": "3ea1352a-6654-444d-9357-62816ccbd2b3",
        "name": "Praveen",
        "email": "email@mydomain.com"
      }
    ]
  }
}

Of course the above example is basic. But in certain cases, Aliases are necessary for the query to work. For example, if you have more than one top level field in the same query with different arguments, then you need to alias it. For example:

# Query with different arguments

query {
  users(order_by: {created_at: desc}) {
    id
    name: full_name
    email: email_addr
  }
  users(order_by: {created_at: asc}) {
    id
    name: full_name
    email: email_addr
  }
}

# Response is an error

{
  "errors": [
    {
      "extensions": {
        "path": "$.selectionSet",
        "code": "validation-failed"
      },
      "message": "cannot merge fields with different arguments under the same alias: \"users\""
    }
  ]
}

The above query doesn't work because we are using different arguments for the same top level field called users. (Note the different order_by object). Now for this to work, we need to make use of Aliases. The above query can be rewritten in the following format with alias for atleast one or both for it to work.

query {
  usersByDesc: users(order_by: {created_at: desc}) {
    id
    name: full_name
    email: email_addr
  }
  usersByAsc: users(order_by: {created_at: asc}) {
    id
    name: full_name
    email: email_addr
  }
}

GraphQL Aliases are dynamic, written on the client making the request. But as you can see, this is a workaround for use cases where you want the selection set to be named more readable. It is not prudent to write this for every query from every client making this request for modifying trivial fields.

Server Side Customisation with Hasura

Hasura lets you customise the field names at the server side. The tables and the columns created in Postgres can be customised to have a different name that can be used while querying. For example, the default root field names generated for a table named users are:

Queries/Subscriptions:

• users
• users_by_pk
• users_aggregate

Mutations:

• insert_users
• delete_users
• update_users

The above root fields and the names of the column fields can now be customized. In Console, you can head to the Modify tab of the corresponding table under Data. For example, we can now change the field name of email_addr to email so that clients can now query without aliasing on the frontend.

So the following query should work after customising both the email_addr and full_name fields with Hasura.

query {
  users {
    id
    name
    email
  }
}

Do note that, once you customise the fields to have a different name, you can no longer make the query with the original field names that you used before the customisation. Please ensure that your client apps are in sync with this change as once you begin using custom names, requests with the original field names will result in an error.

Liquid error: internal

Now you can use your favorite naming conventions like camelCase or snake_case without worrying about the underlying postgres schema.