Metadata API Reference: Remote Relationships

Introduction

Remote Relationships allow you to join tables with remote schemas.

Supported from

The metadata API is supported for versions v2.0.0 and above and replaces the older schema/metadata API.

create_remote_relationship

create_remote_relationship is used to create a new remote relationship with an existing remote schema.

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

{
   "type":"create_remote_relationship",
   "args":{
      "name": "sample_remote_relationship",
      "table": "users",
      "hasura_fields": ["id"],
      "remote_schema": "my-remote-schema",
      "remote_field": {
        "messages": {
           "arguments": {
              "id":"$id"
           }
        }
      }
   }
}

Args syntax

Key Required Schema Description
name true RemoteRelationshipName Name of the remote relationship
table true QualifiedTable Object with table name and schema
hasura_fields true [PGColumn | ComputedFieldName] Column/Computed field(s) in the table that is used for joining with remote schema field. All join keys in remote_field must appear here.
remote_schema true RemoteSchemaName Name of the remote schema to join with
remote_field true RemoteField The schema tree ending at the field in remote schema which needs to be joined with.

update_remote_relationship

update_remote_relationship is used to update an existing remote relationship.

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

{
  "type": "update_remote_relationship",
  "args": {
     "name": "sample_remote_relationship",
     "table": "users",
     "hasura_fields": ["id"],
     "remote_schema": "my-remote-schema",
     "remote_field": {
       "posts": {
          "arguments": {
             "id": "$id",
             "likes": {
                "lte":"1000"
             }
          }
       }
     }
  }
}

Args syntax

Key Required Schema Description
name true RemoteRelationshipName Name of the remote relationship
table true QualifiedTable Object with table name and schema
hasura_fields true [PGColumn] Column(s) in the table that is used for joining with remote schema field. All join keys in remote_field must appear here.
remote_schema true RemoteSchemaName Name of the remote schema to join with
remote_field true RemoteField The schema tree ending at the field in remote schema which needs to be joined with.

delete_remote_relationship

delete_remote_relationship is used to delete an existing remote relationship.

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

{
    "type" : "delete_remote_relationship",
    "args" : {
       "table":{
          "name":"users",
          "schema":"public"
       },
       "name":"sample_remote_relationship"
    }
}

Args syntax

Key Required Schema Description
table true QualifiedTable Object with table name and schema
name true RemoteRelationshipName Name of the remote relationship