Postgres: Remote schema relationships

Introduction

Remote schema relationships extend the concept of joining data across tables, to joining 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.

These APIs can be custom GraphQL servers you write, third party SaaS APIs, or even other Hasura instances.

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.

Note

To see example use cases, check out this blog post.

Supported from

Remote schema relationships are supported from versions v1.3.0 and above.

Create remote schema relationships

Step 0: Add a remote schema

Add a remote schema as described here.

Step 1: Open the remote relationship section

  • From your table, go to the Relationships tab.
  • Click the Add a remote relationship button.
Opening the remote relationship section

Step 2: Define the relationship

The following fields can be defined for a remote schema relationship:

  • Name: Define a name for the relationship.
  • Remote Schema: Select a remote schema among all the ones you’ve created.
  • Configuration: Set up the join configuration, to inject values as input arguments of the remote schema field.
    • From column: Input injected from table column values.
    • From static value: Input injected from a static value of your choice.

For this example, we assume that our schema has a users table with the fields name and auth0_id.

You can add a remote schema relationship by adding it to the tables.yaml in the metadata directory:

 - table:
     schema: public
     name: users
   remote_relationships:
   - definition:
       remote_field:
         auth0profile:
           arguments:
             id: $auth0_id
       hasura_fields:
       - auth0_id
       remote_schema: auth0
     name: auth0

Apply the metadata by running:

hasura metadata apply

You can add a remote schema relationship by using the create_remote_relationship metadata API:

POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "create_remote_relationship",
  "args": {
    "name": "auth0_profile",
    "table": "users",
    "hasura_fields": [
      "auth0_id"
    ],
    "remote_schema": "auth0",
    "remote_field": {
      "auth0": {
        "arguments": {
          "auth0_id": "$auth0_id"
        }
      }
    }
  }
}

In this example, we’ve added a remote schema which is a wrapper around Auth0’s REST API (see example here).

  1. We name the relationship auth0_profile.
  2. We select the auth0 schema that we’ve added.
  3. We set up the config to join the auth0_id input argument of our remote schema field to the auth0_id column of this table (in this case, the users table).

Step 3: Explore with GraphiQL

In the GraphiQL tab, test out your remote schema relationship.

query {
  users {
    name
    auth0_profile {
      nickname
      email
      last_login
    }
  }
}
query { users { name auth0_profile { nickname email last_login } } }
{ "data": { "users": [ { "name": "Daenerys Targaryen", "auth0_profile": { "nickname": "Stormborn", "email": "mother.of.dragons@unburnt.com", "last_login": "2019-05-19T01:35:48.863Z" } } ] } }

Remote schema relationship permissions

Remote schema relationship permissions are derived from the remote schema permissions defined for the role. When a remote relationship cannot be derived, the remote relationship field will not be added to the schema for the role.

Some of the cases in which a remote relationship cannot be derived are:

  1. There are no remote schema permissions defined for the role.
  2. The role doesn’t have access to the field or types that are used by the remote relationship.

Note

Remote relationship permissions apply only if remote schema permissions are enabled in graphql-engine.