Naming conventions for GraphQL schema

When you build a GraphQL API with Hasura, the GraphQL Engine automatically generates names for the GraphQL schema objects.

Starting with Hasura v2.8.0, you can customize the name of fields, types, and arguments.

Why would you customize the names? In certain use cases, one Hasura application might have multiple databases. With the "naming convention" feature, you can:

  • group together all fields belonging to a database
  • solve conflicts with existing GraphQL objects
  • easily identify fields & types of a particular database

There are 2 naming conventions available - hasura-default and graphql-default. By default, Hasura applications use the hasura-default naming convention.

Naming convention feature in Hasura

This article will help you get started with the "naming convention" feature.

How to enable the Naming Convention feature

The "naming convention" feature is experimental, meaning that you need to enable it in the "Env vars" section from your Hasura project settings.

Enable naming convention feature in Hasura

After adding the env variable, navigate to the "Data Manager" page and click on the "Edit" button from your chosen database (in case you have multiple databases).

Data manager in Hasura

Then scroll until you see the "GraphQL Field Customization" field. Click on it to expand the section.

GraphQL field customizations Hasura

In the new section, you can choose a different naming convention and customize the root & type names.

Try it out via Hasura

This article uses a Hasura application with 2 databases. The first database holds information about users and their notes. The second database stores private notes.

Example Hasura app

If you want to follow along, the quickest way to use Hasura is via the Hasura Cloud. Create a new Hasura project and launch the console.

Deploy to Hasura button

Note: If you prefer local development using Docker, check out the documentation on getting started with Docker.

Root fields namespace

Looking at the "Explorer" tab, you cannot determine which tables belong to which database. With the naming convention feature, you can group all tables belonging to a database.

For example, let's use a custom namespace for the database with "public" notes.

GraphQL Field Customization

If you navigate to the Hasura console, you can see all the tables from the public database under the public namespace. Now it's easier to see which tables belong to which database.

Hasura naming convention namespace example

You could go a step further and use a namespace for the other database as well. You could group all the tables from that database under the private namespace. Thus, you would have the public and private namespaces.

Different naming convention

By default, all Hasura applications use the hasura-default naming convention. With hasura-default:

  • all names use snake casing (snake_case)
  • enum values are not changed

If you want to change to another naming convention, you can use graphql-default. In this naming convention:

  • PascalCase is used for type names
  • camelCase is used for field names and arguments
  • UPPERCASE is used for enum values

Let's change the naming convention for the second database (private notes) to graphql-default.

Change naming conventions in Hasura

The figure below illustrates how the GraphQL query and the response look with the graphql-default naming convention.

graphql-default naming convention in Hasura

This example shows how to change the naming convention for one source. However, you can set a default naming convention for all the sources in a Hasura application.

You can do it by setting the environment variable HASURA_GRAPHQL_DEFAULT_NAMING_CONVENTION to the preferred naming convention.

Prefixes and suffixes

Lastly, you can customize the root fields and type names by adding prefixes/suffixes. Let's assume you want to prefix and suffix public notes with public_ and _db, respectively.

Navigate to the "GraphQL Field Customization" section and add the prefix and suffix for the root fields.

Adding a prefix and suffix for root fields in Hasura

If you navigate to the Hasura console, you should see them applied to the root fields.

Showing prefixes and suffixes for root fields in Hasura

Similarly, you can add a prefix and suffix for type names. In the "GraphQL Field Customization" section, move the values public_ and _db from "Root Fields" to "Type Names".

Prefix and suffix for type names in Hasura

Looking at the image, you can see that the type names now contain the custom prefix and suffix.

Summary

The "Naming Convention" feature makes it easier to identify fields & types of a particular database. You can use namespaces, prefixes, and suffixes to organize your application. The documentation for naming conventions is available here.

There is also a video talking about this feature.

07 Sep, 2022

4 MIN READ

Share
banner-illustration-image
Blog
07 Sep, 2022
Email
Subscribe to stay up-to-date on all things Hasura. One newsletter, once a month.
Loading...
v3-pattern
Accelerate development and data access with radically reduced complexity.