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:

• Remote Schema to Remote Schema (RS-to-RS) Joins
• Database to Database (DB-to-DB) Joins
• Database to Remote Schema (DB-to RS) Joins
• Remote Schema to Database (RS-to-DB) Joins

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

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.

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 {
  PACKING
  SHIPPED
  DELIVERED
}

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.

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

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.

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 {
    name
    address
    order_status {
      orderId
      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.