This guide gives a brief overview of Hasura and defines important concepts. This guide includes, step-by-step, how to set up your Hasura and how to insert and get data from a GraphQL API.

Hasura in one sentence:

Hasura connects to your databases and instantly gives you a production-ready GraphQL API.
Hasura is between your GraphQL API (top) and database (bottom)

More specifically, Hasura generates a GraphQL API based on your tables, columns and database structure. GraphQL is mostly known as a way to GET data, but Hasura generates full capabilities of  Create, Read, Update and Delete. All via GraphQL.

But let's explore what GraphQL is and why Facebook, Github and other big organizations are adopting GraphQL.

What is GraphQL?

GraphQL is a query language for your API. GraphQL enables clients to ask for exactly the data they need, and nothing more.

What do you mean "the data you need"?

Simple. GraphQL gives you the data you want. GraphQL does not care if the data you need is in different tables, databases or even in different services. GraphQL will stitch everything together for you and give you the data you need.

What do you mean "nothing more"?

"Nothing more" means you specify exactly the data you want you wont get anything else. Data you don't need, you don't get. No over head. You will get the data you need, and nothing more.

Here is an example. Let's say you have a table of cities.

id name population coordinate
1 Stockholm 1515017 (59.329444,18.068611)
2 Amsterdam 838338 (2.373056,4.892222)
3 Bangalore 8443675 (12.971389,77.594444)

And you only care about id, name and population (not the coordinates). This is simple with GraphQL. All you do is:

query {
  cities {
    id
    name
    population
  }
}
GraphQL query without coordinates

And you will get the response back:

{
  "data": {
    "cities": [
      {
        "id": 1,
        "name": "Stockholm",
        "population": 1515017
      },
      {
        "id": 2,
        "name": "Amsterdam",
        "population": 838338
      },
      {
        "id": 3,
        "name": "Bangalore",
        "population": 8443675
      }
    ]
  }
}
GraphQL response without coorinates

GraphQL can also connect multiple tables based on a relation, and get the data you need in one request. Let's see an example.

We will continue work with our cities table, and we will add a countries table:

id name population
1 India 1339000000
2 Netherlands 17180000
3 Sweden 10120000

We will make a relation between the cities and countries table. We do this by adding a country_id to every cities row. This is our updated cities table:

id name population coordinate country_id
1 Stockholm 1515017 (59.329444,18.068611) 3
2 Amsterdam 838338 (2.373056,4.892222) 2
3 Bangalore 8443675 (12.971389,77.594444) 1

With GraphQL we can make a single request to receive information about both cities and countries, and how they relate to each other:

query {
  cities {
    id
    name
    population
    country {
      name
    }
  }
}
Our GraphQL query
{
  "data": {
    "cities": [
      {
        "id": 1,
        "name": "Stockholm",
        "population": 1515017,
        "country": {
          "name": "Sweden"
        }
      },
      {
        "id": 2,
        "name": "Amsterdam",
        "population": 838338,
        "country": {
          "name": "Netherlands"
        }
      },
      {
        "id": 3,
        "name": "Bangalore",
        "population": 8443675,
        "country": {
          "name": "India"
        }
      }
    ]
  }
}
Our GraphQL response

We made a single query to get the data we wanted. The data we wanted was spread out in two different tables. But we only had to do a single request to get the data. This is the power of GraphQL.

Ok, but what has Hasura to do with all this?

Hasura creates the whole GraphQL API for you. If it was not for Hasura, you would have to write the GraphQL backend your self. Hasura automates everything and saves you a lot of work.

Subscriptions

Subscriptions in GraphQL lets you get realtime updates. It could be that a city gets updated, inserted, or deleted.

subscription {
  cities {
    id
    name
    population
    country {
      name
    }
  }
}

With Hasura you can transform any single query to a subscription. Now, when anything changes that is relevant for your subscription you instantly get the new data.

GraphQL to insert, update and delete data

GraphQL is a powerful technology to query data, but it can also be used to insert, update and delete data. Hasura also automatically generates everything you need to do just that.

Here is an example on how to use GraphQL to insert a city:

mutation {
  insert_cities (
    objects: [{
      name: "New York City",
      population: 8170000,
      coordinate: '40.781944,-73.966111'
    }]
  ) {
    affected_rows
  }
}
Insert New York City.

And update:

mutation {
  update_cities (
    _set: {
      population: 8175133
    }
    where: {
      id: {
        _eq: 4
      }
    }
  ) {
    affected_rows
  }
}
Update New York with more specific population data.

And delete:

mutation {
  delete_cities (
    where: {
     population: { _gt: 10000000}}
  ) {
    affected_rows
  }
}
Delete all cities that has more than 10000000 people.

In addition to automatically provide the GraphQL API based on the database, Hasura also provides a console. The Hasura console.

Hasura console

Hasura console is much like phpMyAdmin. It's a web interface to manage your database. You can, among other things, create tables, add data and run test GraphQL queries.

Managing your database

Manage all your tables. Manage each column, add foreign keys and other constraints. Hasura console is a powerful tool to manage your whole database.

Hasura database management

GraphiQL

Test GraphQL queries and mutations on the data in your database.

Hasura GraphiQL

Remote schema

Add a remote schema. A remote schema is an external GraphQL endpoint.

Hasura remote schema

Managing events

Create webhooks based on database events. You could for example trigger a webhook that sends an email when a new user is inserted in the database.

Hasura event triggers

Start a Hasura instance

To be able to follow this guide you need to set up Hasura. The simplest way to quickly get your own Hasura instance is to create a Nhost project. Every Nhost project comes with Hasura, together with PostgreSQL, authentication and storage.

Log in to your Nhost account and create your project.

Create a new Nhost project

Nhost takes a few seconds to create your project. Hasura is now available for you and the Hasura console URL is presented to you on the dashboard.

The Nhost project is created with Hasura

Use the HASURA_ADMIN_SECRET (also presented in the dashboard) to login to your Hasura web console.

Log in to the Hasura console

In the Hasura web console you have full access to managing Hasura and your database.

Logged in to the Hasura console

Summary

This was a brief overview of Hasura, what it is and what it can do. We have explained that Hasura creates a GraphQL API based on your database. Hasura also provides a console where you can manage your database.

GraphQL is a query language that lets you get data with a relations in an easy and intuitive matter.