Metadata API Reference: Remote Relationships
Introduction
Remote Relationships allow you to join tables with remote schemas or tables on other databases.
Supported from
The metadata API is supported for versions v2.0.0 and above and
replaces the older schema/metadata API.
pg_create_remote_relationship
pg_create_remote_relationship is used to create a new remote relationship on
a Postgres table to an existing remote schema or to a table on a different
database.
When the target is a remote schema.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"pg_create_remote_relationship",
"args":{
// name of the remote relationship
"name": "messages",
// name of the database
"source": "app_db",
// name of the table in the above database on which the relationship
// is being defined
"table": "users",
"definition": {
// this remote relationship is being defined to a resolver on a
// remote schema
"to_remote_schema": {
// name of the target remote schema
"remote_schema": "forum_api",
// the fields on the table that need to be selected to pass the
// required data to the remote schema's resolver
"lhs_fields": ["id"],
// the join condition - this would generate this upstream request:
// query {
// messages(id: id_from_users_table) { .. }
// }
"remote_field": {
"messages": {
"arguments": {
"user_id":"$id"
}
}
}
}
}
}When the target is a table on a different database.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"pg_create_remote_relationship",
"args":{
// name of the remote relationship
"name": "orders",
// name of the database
"source": "app_db",
// name of the table in the above database on which the relationship
// is being defined
"table": "users",
"definition": {
"to_source": {
// the type of the relationship, an 'object' (many-to-one) or an
// 'array' (one-to-many)
"relationship_type": "array",
// the database where the target table exists
"source": "store_db",
// name of the table which is the target of the remote
// relationship
"table": "orders"
// the join condition is specified by a mapping of columns from
// the source's table to the target's table, i.e,
// app_db.users.id = store_db.orders.user_id
"field_mapping": {
"id": "user_id"
}
}
}
}
}
Args syntax
| Key | Required | Schema | Description |
|---|---|---|---|
| name | true | RemoteRelationshipName | Name of the remote relationship |
| source | false | SourceName | Name of the source database of the table (default: default) |
| table | true | TableName | Name of the table on which the relationship is being defined |
| definition | true | RemoteRelationshipDefinition | Definition of the remote relationship |
Old format
Prior to v2.0.10, pg_create_remote_relationship only supported creating
remote relationships to remote schemas and as such it supported a different
format which is now considered legacy. graphql-engine supports this legacy
syntax but we highly recommend you to migrate to the newer format.
Old format example
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"pg_create_remote_relationship",
"args":{
"name": "name_of_the_remote_relationship",
"table": "users",
"hasura_fields": ["id"],
"remote_schema": "my-remote-schema",
"remote_field": {
"messages": {
"arguments": {
"user_id":"$id"
}
}
}
}
}
Old format args syntax
| Key | Required | Schema | Description |
|---|---|---|---|
| name | true | RemoteRelationshipName | Name of the remote relationship |
| source | false | SourceName | Name of the source database of the table (default: default) |
| 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 |
pg_update_remote_relationship
pg_update_remote_relationship is used to update the definition of an
existing remote relationship defined on a Postgres table.
When the target is a remote schema.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"pg_update_remote_relationship",
"args":{
"name": "name_of_the_remote_relationship",
"source": "name_of_the_source",
"table": "users",
// the updated definition
"definition": {
"to_remote_schema": {
"remote_schema": "name_of_the_target_remote_schema",
"lhs_fields": ["id"],
"remote_field": {
"messages": {
"arguments": {
"user_id":"$id"
}
}
}
}
}
}When the target is a table on a different database.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"pg_update_remote_relationship",
"args":{
"name": "name_of_the_remote_relationship",
"source": "name_of_the_source",
"table": "users",
// the updated definition
"definition": {
"to_source": {
"relationship_type": "array",
"source": "name_of_the_target_source",
"table": "table_on_the_target_source"
"field_mapping": {
"user_id": "user_id"
}
}
}
}
}
Args syntax
| Key | Required | Schema | Description |
|---|---|---|---|
| name | true | RemoteRelationshipName | Name of the remote relationship |
| source | false | SourceName | Name of the source database of the table (default: default) |
| table | true | TableName | Name of the table on which the relationship is being defined |
| definition | true | RemoteRelationshipDefinition | Definition of the remote relationship |
Old format
Prior to v2.0.10, pg_update_remote_relationship only supported updating
remote relationships to remote schemas and as such it supported a different
format which is now considered legacy. graphql-engine supports this legacy
syntax but we highly recommend you to migrate to the newer format.
Old format example
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "pg_update_remote_relationship",
"args": {
"name": "name_of_the_remote_relationship",
"table": "users",
"source": "name_of_the_source",
"hasura_fields": ["id"],
"remote_schema": "my-remote-schema",
"remote_field": {
"posts": {
"arguments": {
"user_id": "$id",
"likes": {
"lte":"1000"
}
}
}
}
}
}
Old format args syntax
| Key | Required | Schema | Description |
|---|---|---|---|
| name | true | RemoteRelationshipName | Name of the remote relationship |
| source | false | SourceName | Name of the source database of the table (default: default) |
| 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. |
pg_delete_remote_relationship
pg_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" : "pg_delete_remote_relationship",
"args" : {
"source": "name_of_the_source",
"table": {
"name":"users",
"schema":"public"
},
"name":"name_of_the_remote_relationship"
}
}
Args syntax
| Key | Required | Schema | Description |
|---|---|---|---|
| source | false | SourceName | Name of the source database of the table (default: default) |
| table | true | TableName | Object with table name and schema |
| name | true | RemoteRelationshipName | Name of the remote relationship |
citus_create_remote_relationship
citus_create_remote_relationship is used to create a new remote relationship
on a Citus table to an existing remote schema or to a table on a different
database.
When the target is a remote schema.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"citus_create_remote_relationship",
"args":{
// name of the remote relationship
"name": "messages",
// name of the database
"source": "app_db",
// name of the table in the above database on which the relationship
// is being defined
"table": "users",
"definition": {
// this remote relationship is being defined to a resolver on a
// remote schema
"to_remote_schema": {
// name of the target remote schema
"remote_schema": "forum_api",
// the fields on the table that need to be selected to pass the
// required data to the remote schema's resolver
"lhs_fields": ["id"],
// the join condition - this would generate this upstream request:
// query {
// messages(user_id: id_from_users_table) { .. }
// }
"remote_field": {
"messages": {
"arguments": {
"user_id":"$id"
}
}
}
}
}
}When the target is a table on a different database.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"citus_create_remote_relationship",
"args":{
// name of the remote relationship
"name": "orders",
// name of the database
"source": "app_db",
// name of the table in the above database on which the relationship
// is being defined
"table": "users",
"definition": {
"to_source": {
// the type of the relationship, an 'object' (many-to-one) or an
// 'array' (one-to-many)
"relationship_type": "array",
// the database where the target table exists
"source": "store_db",
// name of the table which is the target of the remote
// relationship
"table": "orders"
// the join condition is specified by a mapping of columns from
// the source's table to the target's table, i.e,
// app_db.users.id = store_db.orders.user_id
"field_mapping": {
"id": "user_id"
}
}
}
}
}
Args syntax
| Key | Required | Schema | Description |
|---|---|---|---|
| name | true | RemoteRelationshipName | Name of the remote relationship |
| source | false | SourceName | Name of the source database of the table (default: default) |
| table | true | TableName | Name of the table on which the relationship is being defined |
| definition | true | RemoteRelationshipDefinition | Definition of the remote relationship |
citus_update_remote_relationship
citus_update_remote_relationship is used to update the definition of an
existing remote relationship defined on a Citus table.
When the target is a remote schema.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"citus_update_remote_relationship",
"args":{
"name": "name_of_the_remote_relationship",
"source": "name_of_the_source",
"table": "users",
// the updated definition
"definition": {
"to_remote_schema": {
"remote_schema": "name_of_the_target_remote_schema",
"lhs_fields": ["id"],
"remote_field": {
"messages": {
"arguments": {
"user_id":"$id"
}
}
}
}
}
}When the target is a table on a different database.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"citus_update_remote_relationship",
"args":{
"name": "name_of_the_remote_relationship",
"source": "name_of_the_source",
"table": "users",
// the updated definition
"definition": {
"to_source": {
"relationship_type": "array",
"source": "name_of_the_target_source",
"table": "table_on_the_target_source"
"field_mapping": {
"user_id": "user_id"
}
}
}
}
}
Args syntax
| Key | Required | Schema | Description |
|---|---|---|---|
| name | true | RemoteRelationshipName | Name of the remote relationship |
| source | false | SourceName | Name of the source database of the table (default: default) |
| table | true | TableName | Name of the table on which the relationship is being defined |
| definition | true | RemoteRelationshipDefinition | Definition of the remote relationship |
citus_delete_remote_relationship
citus_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" : "citus_delete_remote_relationship",
"args" : {
"source": "name_of_the_source",
"table": {
"name":"users",
"schema":"public"
},
"name":"name_of_the_remote_relationship"
}
}
Args syntax
| Key | Required | Schema | Description |
|---|---|---|---|
| source | false | SourceName | Name of the source database of the table (default: default) |
| table | true | TableName | Name of the table |
| name | true | RemoteRelationshipName | Name of the remote relationship |
mssql_create_remote_relationship
mssql_create_remote_relationship is used to create a new remote relationship
on an mssql table to an existing remote schema or to a table on a different
database.
When the target is a remote schema.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"mssql_create_remote_relationship",
"args":{
// name of the remote relationship
"name": "messages",
// name of the database
"source": "app_db",
// name of the table in the above database on which the relationship
// is being defined
"table": "users",
"definition": {
// this remote relationship is being defined to a resolver on a
// remote schema
"to_remote_schema": {
// name of the target remote schema
"remote_schema": "forum_api",
// the fields on the table that need to be selected to pass the
// required data to the remote schema's resolver
"lhs_fields": ["id"],
// the join condition - this would generate this upstream request:
// query {
// messages(user_id: id_from_users_table) { .. }
// }
"remote_field": {
"messages": {
"arguments": {
"user_id":"$id"
}
}
}
}
}
}When the target is a table on a different database.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"mssql_create_remote_relationship",
"args":{
// name of the remote relationship
"name": "orders",
// name of the database
"source": "app_db",
// name of the table in the above database on which the relationship
// is being defined
"table": "users",
"definition": {
"to_source": {
// the type of the relationship, an 'object' (many-to-one) or an
// 'array' (one-to-many)
"relationship_type": "array",
// the database where the target table exists
"source": "store_db",
// name of the table which is the target of the remote
// relationship
"table": "orders"
// the join condition is specified by a mapping of columns from
// the source's table to the target's table, i.e,
// app_db.users.id = store_db.orders.user_id
"field_mapping": {
"id": "user_id"
}
}
}
}
}
Args syntax
| Key | Required | Schema | Description |
|---|---|---|---|
| name | true | RemoteRelationshipName | Name of the remote relationship |
| source | false | SourceName | Name of the source database of the table (default: default) |
| table | true | TableName | Name of the table on which the relationship is being defined |
| definition | true | RemoteRelationshipDefinition | Definition of the remote relationship |
mssql_update_remote_relationship
mssql_update_remote_relationship is used to update the definition of an
existing remote relationship defined on an MS SQL table.
When the target is a remote schema.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"mssql_update_remote_relationship",
"args":{
"name": "name_of_the_remote_relationship",
"source": "name_of_the_source",
"table": "users",
// the updated definition
"definition": {
"to_remote_schema": {
"remote_schema": "name_of_the_target_remote_schema",
"lhs_fields": ["id"],
"remote_field": {
"messages": {
"arguments": {
"user_id":"$id"
}
}
}
}
}
}When the target is a table on a different database.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"mssql_update_remote_relationship",
"args":{
"name": "name_of_the_remote_relationship",
"source": "name_of_the_source",
"table": "users",
// the updated definition
"definition": {
"to_source": {
"relationship_type": "array",
"source": "name_of_the_target_source",
"table": "table_on_the_target_source"
"field_mapping": {
"id": "user_id"
}
}
}
}
}
Args syntax
| Key | Required | Schema | Description |
|---|---|---|---|
| name | true | RemoteRelationshipName | Name of the remote relationship |
| source | false | SourceName | Name of the source database of the table (default: default) |
| table | true | TableName | Name of the table on which the relationship is being defined |
| definition | true | RemoteRelationshipDefinition | Definition of the remote relationship |
mssql_delete_remote_relationship
mssql_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" : "mssql_delete_remote_relationship",
"args" : {
"source": "name_of_the_source",
"table": {
"name":"users",
"schema":"public"
},
"name":"name_of_the_remote_relationship"
}
}
Args syntax
| Key | Required | Schema | Description |
|---|---|---|---|
| source | false | SourceName | Name of the source database of the table (default: default) |
| table | true | TableName | Name of the table on which the relationship is being defined |
| name | true | RemoteRelationshipName | Name of the remote relationship |
bigquery_create_remote_relationship
bigquery_create_remote_relationship is used to create a new remote relationship
on a BigQuery table to an existing remote schema or to a table on a different
database.
When the target is a remote schema.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"bigquery_create_remote_relationship",
"args":{
// name of the remote relationship
"name": "messages",
// name of the database
"source": "app_db",
// name of the table in the above database on which the relationship
// is being defined
"table": {
"dataset": "<source_dataset_name>",
"name": "users"
},
"definition": {
// this remote relationship is being defined to a resolver on a
// remote schema
"to_remote_schema": {
// name of the target remote schema
"remote_schema": "forum_api",
// the fields on the table that need to be selected to pass the
// required data to the remote schema's resolver
"lhs_fields": ["id"],
// the join condition - this would generate this upstream request:
// query {
// messages(user_id: id_from_users_table) { .. }
// }
"remote_field": {
"messages": {
"arguments": {
"user_id":"$id"
}
}
}
}
}
}When the target is a table on a different database.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type": "bigquery_create_remote_relationship",
"args": {
// name of the remote relationship
"name": "orders",
// name of the database
"source": "app_db",
// name of the table in the above database on which the relationship
// is being defined
"table": {
"dataset": "<source_dataset_name>",
"name": "users"
},
"definition": {
"to_source": {
// the type of the relationship, an 'object' (many-to-one) or an
// 'array' (one-to-many)
"relationship_type": "array",
// the database where the target table exists
"source": "store_db",
// name of the table which is the target of the remote
// relationship
"table": {
"name": "orders",
"dataset": "<target_dataset_name>"
},
// the join condition is specified by a mapping of columns from
// the source's table to the target's table, i.e,
// app_db.users.id = store_db.orders.user_id
"field_mapping": {
"id": "user_id"
}
}
}
}
}
Args syntax
| Key | Required | Schema | Description |
|---|---|---|---|
| name | true | RemoteRelationshipName | Name of the remote relationship |
| source | false | SourceName | Name of the source database of the table (default: default) |
| table | true | BigQueryTableName | Name of the table on which the relationship is being defined |
| definition | true | RemoteRelationshipDefinition | Definition of the remote relationship |
bigquery_update_remote_relationship
bigquery_update_remote_relationship is used to update the definition of an
existing remote relationship defined on a BigQuery table.
When the target is a remote schema.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"bigquery_update_remote_relationship",
"args":{
"name": "name_of_the_remote_relationship",
"source": "name_of_the_source",
"table": "users",
// the updated definition
"definition": {
"to_remote_schema": {
"remote_schema": "name_of_the_target_remote_schema",
"lhs_fields": ["id"],
"remote_field": {
"messages": {
"arguments": {
"user_id":"$id"
}
}
}
}
}
}When the target is a table on a different database.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"bigquery_update_remote_relationship",
"args":{
"name": "name_of_the_remote_relationship",
"source": "name_of_the_source",
"table": "users",
// the updated definition
"definition": {
"to_source": {
"relationship_type": "array",
"source": "name_of_the_target_source",
"table": "table_on_the_target_source"
"field_mapping": {
"user_id": "user_id"
}
}
}
}
}
Args syntax
| Key | Required | Schema | Description |
|---|---|---|---|
| name | true | RemoteRelationshipName | Name of the remote relationship |
| source | false | SourceName | Name of the source database of the table (default: default) |
| table | true | BigQueryTableName | Name of the table on which the relationship is being defined |
| definition | true | RemoteRelationshipDefinition | Definition of the remote relationship |
bigquery_delete_remote_relationship
bigquery_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" : "bigquery_delete_remote_relationship",
"args" : {
"source": "name_of_the_source",
"table": {
"name":"users",
"dataset":"some_dataset_name"
},
"name":"name_of_the_remote_relationship"
}
}
Args syntax
| Key | Required | Schema | Description |
|---|---|---|---|
| source | false | SourceName | Name of the source database of the table (default: default) |
| table | true | BigQueryTableName | Name of the table on which the relationship is being defined |
| name | true | RemoteRelationshipName | Name of the remote relationship |
create_remote_schema_remote_relationship
create_remote_schema_remote_relationship is used to create a new remote
relationship on a remote schema's type to a table on a database or to another
remote schema.
Supported types
Currently only object types on a remote schema are supported.
When the target is a remote schema.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"create_remote_schema_remote_relationship",
"args":{
// name of the remote relationship
"name": "messages",
// name of the remote schema
"remote_schema": "users_api",
// the object type in the above remote schema on which the
// relationship is being defined
"type": "user",
"definition": {
// this remote relationship is being defined to a resolver on a
// remote schema
"to_remote_schema": {
// name of the target remote schema
"remote_schema": "forum_api",
// the fields on the table that need to be selected to pass the
// required data to the remote schema's resolver
"lhs_fields": ["id"],
// the join condition - this would generate this upstream request:
// query {
// messages(user_id: id_from_user_type) { .. }
// }
"remote_field": {
"messages": {
"arguments": {
"user_id":"$id"
}
}
}
}
}
}When the target is a table on a different database.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"create_remote_schema_remote_relationship",
"args":{
// name of the remote relationship
"name": "messages",
// name of the remote schema
"remote_schema": "users_api",
// the object type in the above remote schema on which the
// relationship is being defined
"type": "user",
// name of the remote relationship
"definition": {
"to_source": {
// the type of the relationship, an 'object' (many-to-one) or an
// 'array' (one-to-many)
"relationship_type": "array",
// the database where the target table exists
"source": "store_db",
// name of the table which is the target of the remote
// relationship
"table": "orders"
// the join condition is specified by a mapping of columns from
// the remote schema's type to the target's table, i.e,
// users_api.user.id = store_db.orders.user_id
"field_mapping": {
"id": "user_id"
}
}
}
}
}
Args syntax
| Key | Required | Schema | Description |
|---|---|---|---|
| name | true | RemoteRelationshipName | Name of the remote relationship |
| remote_schema | true | RemoteSchemaName | Name of the remote schema |
| type | true | GraphQLName | Name of the type on which the relationship is being defined |
| definition | true | RemoteRelationshipDefinition | Definition of the remote relationship |
update_remote_schema_remote_relationship
update_remote_schema_remote_relationship is used to update an existing remote
relationship defined on a remote schema's type.
When the target is a remote schema.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"update_remote_schema_remote_relationship",
"args":{
"name": "messages",
"remote_schema": "users_api",
"type": "user",
// new definition of the remote relationship
"definition": {
"to_remote_schema": {
"remote_schema": "forum_api",
"lhs_fields": ["id"],
"remote_field": {
"messages": {
"arguments": {
"user_id":"$id"
}
}
}
}
}
}When the target is a table on a different database.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"update_remote_schema_remote_relationship",
"args":{
"name": "messages",
"remote_schema": "users_api",
"type": "user",
// new definition of the remote relationship
"definition": {
"to_source": {
"relationship_type": "array",
"source": "store_db",
"table": "orders"
"field_mapping": {
"id": "user_id"
}
}
}
}
}
Args syntax
| Key | Required | Schema | Description |
|---|---|---|---|
| name | true | RemoteRelationshipName | Name of the remote relationship |
| remote_schema | true | RemoteSchemaName | Name of the remote schema |
| type | true | GraphQLName | Name of the type on which the relationship is being defined |
| definition | true | RemoteRelationshipDefinition | Definition of the remote relationship |
delete_remote_schema_remote_relationship
delete_remote_schema_remote_relationship is used to delete an existing remote
relationship defined on a remote schema's type.
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"type":"delete_remote_schema_remote_relationship",
"args":{
"name": "messages",
"remote_schema": "users_api",
"type": "user"
}
}
Args syntax
| Key | Required | Schema | Description |
|---|---|---|---|
| name | true | RemoteRelationshipName | Name of the remote relationship |
| remote_schema | true | RemoteSchemaName | Name of the remote schema |
| type | true | GraphQLName | Name of the type on which the relationship is being defined |
