Join data from a Database with GraphQL API using Database to Remote Schema Joins

GraphQL Joins allow you to create a unified GraphQL API by joining the data from different GraphQL sources.

With GraphQL Joins, you can federate your queries and mutations across multiple GraphQL sources as if they were a single GraphQL schema. You do not have to write extra code or change the underlying APIs.

Hasura supports the following types of joins:

This article will help you learn about the Database to Remote Schema Joins.

How do DB-to-RS Joins work?

The Database-to-Remote Schema Joins feature enables you to connect the data from your existing database with an external GraphQL service.

That's possible by creating a relationship from a field in the database to a field in the external GraphQL service.

E-Commerce Example with Hasura

For this example, you have a fulfillment service and a Hasura application.

The fulfillment service is an example of a shipping company schema, with each fulfillment having an order ID and a status.

enum Status {

type Fulfillment {
  id: Int!
  orderId: Int!
  status: Status!

type Query {
  fulfillment(orderId: Int!): Fulfillment!
  fulfillments: [Fulfillment]!

There is also a Hasura application that stores the users and keeps track of their orders. When you query the database, you can retrieve the users and their order status.

The figure below shows the structure of the "users" table.

Hasura "users" Table

The next step involves adding the fulfillment service as a remote schema to Hasura.

"fulfillment" Remote Schema

Now that the service is present as a remote schema, you can create a relationship between the database and the "fulfillment" remote schema.

Go to the "users" table, then to the "Relationship" tab, and click the button "Add a remote schema relationship". That opens a new tab where you can configure the relationship.

Adding a new remote schema relationship

For the name, you can choose something like order_status. For the "Remote Schema" field, choose fulfillment. Lastly, for the "Configuration" select fulfillment > orderId > From Column > order_id.

The orderId field from the fulfillment remote schema maps to the order_id field from the Hasura application.

Save the relationship and you are done! You can test the relationship with the following query:

query {
  users {
    order_status {

The query retrieves all users, their order id, and the status of that specific order. Running the query would return something similar:

  "data": {
    "users": [
        "name": "Ali Mar",
        "address": "15 Santana Avenue, Devtown, 471621284",
        "order_status": {
          "orderId": 1,
          "status": "PACKING"

The Hasura application and remote schema are now connected! The users and their order status can be queried simultaneously. You managed to do it without altering the external GraphQL API or writing any code.

If you want to read more about GraphQL Joins, you can do it here.
30 Jun, 2022
Subscribe to stay up-to-date on all things Hasura. One newsletter, once a month.
Accelerate development and data access with radically reduced complexity.