Remote Schema to Remote Schema Relationships

Introduction

Remote Schema to Remote Schema relationships (a.k.a GraphQL joins) extend the concept of joining data across tables, to joining across remote GraphQL sources. Once you create relationships between types from the GraphQL schemas, 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.

Supported from

Relationships from Remote Schema to Remote Schema are supported from versions v2.6.0 and above.

Create Remote Schema relationships

Step 1: Add two Remote Schemas

Add two Remote Schemas as described here, if the schemas aren't already added.

Step 2: Define and create the relationship

The following fields can be defined for a Remote Schema relationship:

• Name: Define a name for the relationship.
• Remote Schemas: Select two Remote Schemas 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 example, let's assume that our first Remote Schema order-remote-schema has a field order(id int, user_id int) and our second Remote Schema user-remote-schema - which is another GraphQL API - has a field user(id int, name text). Now we want to create a relationship between the order field of the first Remote Schema and the user field of the second Remote Schema.

1. We name the relationship user.
2. We select the source type Order of the Remote Schema that we'd like to join.
3. We select user-remote-schema as the reference Remote Schema.
4. We select id as the source field and user_id as the from field.

Console

• Head to the Remote Schema -> [remote-schema-name] -> Relationships tab.

• Click the Add a new relationship button.

  

• Define the relationship and hit Add Relationship.

  

CLI

Update the remote_schemas.yaml file in the metadata directory:

- name: order-remote-schema
  definition:
    url: https://remote-schema-endpoint.com
  remote_relationships:
    - relationships:
        type_name: Order
        name: user
        - definition:
            to_remote_schema:
              remote_schema: user-remote-schema
              lhs_fields:
                - user_id
              remote_field:
                user:
                  arguments:
                    id: $user_id

Apply the Metadata by running:

hasura metadata apply

API

You can add a Remote Schema relationship by using the create_remote_schema_remote_relationship Metadata API and update it by using the update_remote_schema_remote_relationship Metadata API:

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

{
  "type": "create_remote_schema_remote_relationship",
  "args": {
    "name": "user",
    "remote_schema": "order-remote-schema",
    "type_name": "Order",
    "definition": {
      "to_remote_schema": {
        "remote_schema": "user-remote-schema",
        "lhs_fields": ["user_id"],
        "remote_field": {
          "user": {
            "arguments": {
              "id":"$user_id"
            }
          }
        }
      }
    }
  }
}

Step 3: Explore with GraphiQL

In the API tab, test out your Remote Schema relationship.

GraphiQL

Query Variables

Request Headers

Documentation Explorer

⚲

No Schema Available