Schema/Metadata API Reference: Remote Relationships

Introduction

Remote Relationships allow you to join tables with remote schemas.

create_remote_relationship

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

POST /v1/query 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] 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.

update_remote_relationship

update_remote_relationship is used to update an existing remote relationship.

POST /v1/query 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/query 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

RemoteRelationshipName

String

RemoteField

{
   FieldName: {
     "arguments": InputArguments
     "field": RemoteField  # optional
   }
}

RemoteField is a recursive tree structure that points to the field in the remote schema that needs to be joined with. It is recursive because the remote field maybe nested deeply in the remote schema.

Examples:

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

{
   "message": {
      "arguments":{
         "message_id":"$id"
       }
   }
}

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

{
   "messages": {
      "arguments": {
         "limit": 100
      },
      "field": {
        "private": {
          "arguments": {
             "id" : "$id"
          }
        }
      }
   }
}

InputArguments

{
  InputField : $PGColumn | Scalar
}

Table columns can be referred by prefixing $ e.g $id.

« previous | next »
Want to contribute or report missing content?

Powered by Sphinx. | Copyright © 2021 Hasura.