Remote Joins: A GraphQL API to join across your database and other data-sources
Tags: graphql, hasura, postgres, serverless
Published: 2019-07-26 09:23:54

![](https://thepracticaldev.s3.amazonaws.com/i/eojjuif7x24wv408azoc.png)
 <figcaption>Remote Joins: A GraphQL API to join across your database and other data-sources</figcaption>

We've been working hard on a core Hasura feature that will allow you to fetch <i>related</i> data that is in your database and in remote data sources with GraphQL. (Currently in preview, if you'd like to get notified when this is released, do sign up <a href="https://hasura.io/remote-joins" target="_blank">here</a>!)

As developers and teams move to using more and more 3rd party APIs, multiple databases & microservices, data and "the source of truth" is getting spread across these data-sources. Application developers have a hard time getting access to precise slices of data and a lot of dev cycles are spent in bringing all that data together securely.

<i>Remote Joins</i> in Hasura extend the concept of joining data across tables, to being able to join data across tables and remote data sources. Once you create relationships between types from your database and types created from APIs, you can then “join” them by running GraphQL queries. #JoinAllTheThings

<i>Head to <a href="https://github.com/hasura/graphql-engine/pull/2392" target="_blank">the PR</a> to check out more details, read the preview docs, and to try out a test Hasura image that you can spin up. Jump on our <a href="https://discordapp.com/invite/hasura" target="_blank">discord</a> or comment on <a href="https://github.com/hasura/graphql-engine" target="_blank">github</a> and let us know what you think!</i>

Remote joins can join across the database and APIs. These APIs can be custom GraphQL servers you write, 3rd party SaaS APIs, or even other Hasura instances.

Of course, because Hasura is meant to be a GraphQL server that you can expose directly to your apps, Hasura also handles security and authorization while providing remote joins.

<hr>

<h2>Use Case #1: Customer data joined with Account/Billing/Payment information in Stripe</h2>

If you have a payment method on your app that uses Stripe, a lot of account and billing information about your customer resides with Stripe. For example, the customer's saved cards, account balance, billing/invoice history.

![](https://thepracticaldev.s3.amazonaws.com/i/wzrqxwtefi93sn2xceeq.png)
<figcaption>Customer data joined with account, billing, payment-transaction data in Stripe</figcaption>

On your app, you'd typically want to show users their saved cards and invoice history. You'd write code to fetch the right data from the Stripe API for the right users/invoices and return that as an API response to your app.

This is what this setup looks like on Hasura:

<b>Step 1: Setup <a href="https://www.onegraph.com/">OneGraph</a> to connect to your Stripe account</b>
![](https://thepracticaldev.s3.amazonaws.com/i/vbd8fax3oos86vviamqn.png)
<figcaption>Setup OneGraph to connect to your Stripe account</figcaption>

<b>Step 2: Add OneGraph as a remote schema to Hasura</b>
![](https://thepracticaldev.s3.amazonaws.com/i/osqnwcz61slc0l2hipea.png)
<figcaption>Add OneGraph as a remote schema to Hasura</figcaption>

<b>Step 3: Setup a remote relationship from your customer table to the Stripe resolver using the `stripe_customer_id` as the "join" key</b>
![](https://thepracticaldev.s3.amazonaws.com/i/ivkecou95hfijsm84wsu.png)
<figcaption>Your table should have the stripe_customer_id column</figcaption>

![](https://thepracticaldev.s3.amazonaws.com/i/qtcnkew2w3x7b14g6kdw.png)
<figcaption>Setup a remote relationship from your customer table to the Stripe resolver using the stripe_customer_id as the "join" key</figcaption>

<b>Step 4: Make GraphQL queries to fetch customer and stripe information in one shot!</b>
![](https://thepracticaldev.s3.amazonaws.com/i/hzuulvy137illv09k31u.png)
<figcaption>Make GraphQL queries to fetch customer and stripe information in one shot!</figcaption>

<hr>

<h2>Use-case #2: User data joined with profile information in Auth0</h2>

When you use an external authentication provider (or even an authentication/user management microservice that your team doesn't own directly), there will be some information that is only provided by the auth service. For example, `last_login`, `verified_email`, `login_count` and so on.

In your database, you would typically have a user table that has an `auth0_id`. To fetch auth specific information, you would need to use this id and the Auth0 API.

![](https://thepracticaldev.s3.amazonaws.com/i/nrv4ckecyf0um7effj6x.png)
<figcaption>User data joined with account/profile/auth information in Auth0</figcaption>

Here's how Hasura helps you automate that process:

<b>Step 1: Write a serverless function that wraps the Auth0 profile API in a GraphQL query resolver.</b>
![](https://thepracticaldev.s3.amazonaws.com/i/dvcao1jz4a3qudmq3wb7.png)
<figcaption>Write a serverless function that wraps the Auth0 profile API in a GraphQL query resolver. </figcaption>

<b>Step 2: Connect this as a remote schema in Hasura</b>
![](https://thepracticaldev.s3.amazonaws.com/i/ue4p4y8gexh8p7a92w8y.png)
<figcaption>Connect this as a remote schema in Hasura</figcaption>

<b>Step 3: Go to the User table on Hasura and add a "remote relationship" to the schema you added above</b>
![](https://thepracticaldev.s3.amazonaws.com/i/lnacxrbyp0kj73w9q9j2.png)
<figcaption>The auth0_id identifier is the "join" key from your database</figcaption>

![](https://thepracticaldev.s3.amazonaws.com/i/gi0zrmmumst5b0szwuna.png)
<figcaption>Add a "remote relationship" to the auth0 schema</figcaption>

<b>Step 4: Make a GraphQL query to query data from the user table and the Auth0 profile information simultaneously</b>
![](https://thepracticaldev.s3.amazonaws.com/i/cpm3abrylj4b077c680e.png)
<figcaption>Make a GraphQL query to query data from the user table and the Auth0 profile information simultaneously</figcaption>

<hr>

<h2>Use-case #3: Joining data across 2 separate databases<h2>

![](https://thepracticaldev.s3.amazonaws.com/i/alkei41fqwuiktgyuws7.png)
<figcaption>Joining data across 2 databases</figcaption>

The title says it all 🤓. And here's how this works with Hasura!

<b>Step 1: Setup Hasura to point to Database 1 and Database 2 with the right access control rules so that your GraphQL API is secure.</b>
![](https://thepracticaldev.s3.amazonaws.com/i/z8bc7hnxue0z8k03rmj7.png)
<figcaption>The "remote" Hasura + Postgres</figcaption>

![](https://thepracticaldev.s3.amazonaws.com/i/vq09byicsi5ut7mfqeke.png)
<figcaption>The "primary" Hasura + Postgres</figcaption>

<b>Step 2: On the Hasura of your "primary" database, add the second Hasura as a remote schema</b>
![](https://thepracticaldev.s3.amazonaws.com/i/cagseommrdjhw6697k7q.png)
<figcaption>On the Hasura of your "primary" database, add the second Hasura as a remote schema</figcaption>

<b>Step 3: Set up remote relationships from any table in your "primary" database to  resolvers in the other database.</b>
![](https://thepracticaldev.s3.amazonaws.com/i/ukqmeq9956kbz4rd6tsv.png)
<figcaption>Set up remote relationships from any table in your "primary" database to resolvers in the other database</figcaption>

<b>Step 4: Run a GraphQL query that joins data across 2 databases!</b>
![](https://thepracticaldev.s3.amazonaws.com/i/nk7544owsgm4qpyzsbfc.png)
<figcaption>A GraphQL query that joins data across 2 databases!</figcaption>

<hr>

<b>Note:</b> Hasura Remote Joins is a type of GraphQL federation, similar to Apollo Federation. The key difference is that Apollo Federation aims to help organisations with multiple GraphQL teams “federate” a global GraphQL schema. Hasura remote joins help you “join” across multiple data-sources (or GraphQL microservices) so that you get a unified GraphQL API. This unified GraphQL API might be required for a team that has multiple sources of data for their application or might be a unified GraphQL API across various teams (like Apollo Federation) maintained by a central data API team in the organisation.

Try it out and let us know what you think! We ❤️ your feedback. Hit us up on our <a href="https://github.com/hasura/graphql-engine" target="_blank">github</a> or on <a href="https://discordapp.com/invite/hasura" target="_blank">discord</a>. Remote Joins will be out of preview and released very very soon for production use!

<hr>

<i>This article was originally written and published by <a href="https://twitter.com/tanmaigo" target="_blank">Tanmai Gopal</a> on the <a href="https://blog.hasura.io/remote-joins-a-graphql-api-to-join-database-and-other-data-sources/" target="_blank">Hasura blog</a><i>.