docs: add feature docs for federation

This PR adds the following docs:
- Remote relationships for Postgres
  - Remote schema -> Database
  - Remote schema -> Remote schema
- Remote relationships for MS SQL Server
  - Database -> Database
  - Database -> Remote schema
  - Remote schema -> Database
  - Remote schema -> Remote schema

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/4281
Co-authored-by: Vamshi Surabhi <6562944+0x777@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com>
GitOrigin-RevId: dc6aa4d4cbcfd9c9ddc1df65c7b0f402cc2eafee

docs/docs/graphql/core/data-federation.mdx

@@ -0,0 +1,46 @@
+---
+sidebar_label: Data Federation
+sidebar_position: 13
+description: Join data across remote data sources
+keywords:
+  - hasura
+  - docs
+  - remote join
+  - data federation
+# adding to avoid redirect as this was only index file under the directory
+slug: data-federation/index
+---
+
+# Data Federation
+
+## Introduction
+
+Hasura’s data federation capabilities allow you to compose data from different sources
+that reside in independent data stores but are semantically related. This is done by creating
+a single GraphQL schema from multiple data sources thereby making the data access process
+self-serve, allowing you to query, mutate or federate real-time and stream data across services
+without writing any custom code.
+
+The remote data sources can either be a table from a [database source](/graphql/core/databases/index.mdx),
+a GraphQL API added as a [remote schema](/graphql/core/remote-schemas/index.mdx),
+or a REST API added as an [action](/graphql/core/actions/index.mdx). Once you create
+relationships between types from your database tables, remote schemas and actions, you can then "join" data
+across them by running GraphQL queries.
+
+## Types of remote relationships
+
+Hasura GraphQL engine supports the following relationships across your various data sources:
+
+- [Database to database relationships](/graphql/core/databases/postgres/schema/remote-relationships/remote-source-relationships.mdx): To join
+data across tables between two different database sources, such as order information stored in a Postgres database, and user information stored
+in a separate Postgres or say a SQL Server database.
+- [Database to Remote Schema relationships](/graphql/core/databases/postgres/schema/remote-relationships/remote-schema-relationships.mdx): To
+join data across tables and remote GraphQL APIs. For example, you can join customer data from your tables with account data from Stripe, Spotify,
+or Auth0 via their GraphQL APIs.
+- [Remote Schema to database relationships](/graphql/core/remote-schemas/remote-relationships/remote-schema-db-relationships.mdx): To join
+data from remote GraphQL schemas to database tables. For example connecting account data from Stripe, Spotify or Auth0 GraphQL APIs to customer data in your tables.
+- [Remote Schema to Remote Schema relationships (a.k.a GraphQL joins)](/graphql/core/remote-schemas/remote-relationships/remote-schema-relationships.mdx): To
+join data between two remote GraphQL schemas. For example connecting customer data from your custom GraphQL API to account data from Stripe, Spotify or
+Auth0 GraphQL APIs.
+- [Action to database relationships](/graphql/core/databases/postgres/schema/remote-relationships/action-relationships.mdx): To join data across
+tables and actions (i.e. Rest APIs). For example, you can join user data from your database with the response from a `createUser` action.

docs/docs/graphql/core/databases/bigquery/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "BigQuery",
-  "position": 4
+  "position": 5
 }

docs/docs/graphql/core/databases/citus-hyperscale-postgres/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Citus / Hyperscale",
-  "position": 3
+  "position": 4
 }

docs/docs/graphql/core/databases/connect-db.mdx

@@ -1,6 +1,6 @@
 ---
 sidebar_label: Connecting databases
-sidebar_position: 5
+sidebar_position: 1
 description: Connect a database to Hasura
 keywords:
   - hasura

docs/docs/graphql/core/databases/ms-sql-server/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "MS SQL Server",
-  "position": 2
+  "position": 3
 }

docs/docs/graphql/core/databases/ms-sql-server/schema/remote-relationships/_category_.json

@@ -0,0 +1,4 @@
+{
+    "label": "Remote relationships",
+    "position": 3
+}

docs/docs/graphql/core/databases/ms-sql-server/schema/remote-relationships/index.mdx

@@ -0,0 +1,61 @@
+---
+slug: index
+description: Manage remote relationships with MS SQL Server in Hasura
+keywords:
+  - hasura
+  - docs
+  - ms sql server
+  - schema
+  - relationship
+  - remote relationship
+---
+
+# MS SQL Server: Remote relationships
+
+## Introduction
+
+Remote relationships (aka "remote joins") allow you to join data across
+tables and remote data sources. The remote data source can either be a
+[remote schema](/graphql/core/remote-schemas/index.mdx) or a table from a second database source.
+Once you create relationships between types from your database tables and types created from remote schemas,
+you can then "join" them by running GraphQL queries.
+
+See the following guides on how to create different types of remote
+relationships related to MS SQL Server:
+
+- [Database to database relationships](/graphql/core/databases/ms-sql-server/schema/remote-relationships/remote-source-relationships.mdx): To join
+data across tables between two different database sources, such as order information stored in a SQL Server database, and user information stored
+in a separate SQL Server or say a Postgres database.
+- [Database to Remote Schema relationships](/graphql/core/databases/ms-sql-server/schema/remote-relationships/remote-schema-relationships.mdx): To
+join data across tables and remote GraphQL APIs. For example, you can join customer data from your tables with account data from Stripe, Spotify, or Auth0.
+- [Remote Schema to database relationships](/graphql/core/remote-schemas/remote-relationships/remote-schema-db-relationships.mdx): To join
+data from your remote schemas (such as Stripe, Spotify or Auth0) to customer data from your tables.
+
+## Benefits
+
+Hasura's remote joins architecture provides the following benefits.
+
+- **Security**: Hasura's [authorization model](/graphql/core/auth/authorization/index.mdx) gives
+  you role-based access control. This extends to remote
+  schemas as well. Hasura will [forward your session variables](/graphql/core/remote-schemas/auth/index.mdx)
+  which can be used to implement custom authorization in your remote
+  schemas. Native role-based permissions on remote schemas is in the
+  works.
+- **Performance**: Hasura strives for optimal performance. It creates
+  an efficient execution plan which pushes down most of the
+  heavy-lifting involved to underlying sources. For example, Hasura
+  creates a single efficient query to your database and batches calls
+  to remote schemas to avoid the [n+1
+  problem](https://hasura.io/learn/graphql/intro-graphql/graphql-server/)
+  . More improvements to performance are upcoming.
+- **Schema integrity & consistency**: Hasura has metadata consistency
+  checks at every level. Whenever you add a table or remote schema, 
+  Hasura makes sure that the graph that is exposed is
+  consistent, and that all the relationships make sense at a type
+  level. This helps you in creating robust workflows to test changes
+  in your CI and making safe deployments of your unified graph.
+- **Data federation**: With remote joins, the join, authorization, and
+  consistency checks of added sources all happen at the Hasura layer
+  via metadata. This allows underlying data sources and APIs to evolve
+  independently. Your applications have a unified API to query the
+  full data landscape in your org.

docs/docs/graphql/core/databases/ms-sql-server/schema/remote-relationships/remote-schema-relationships.mdx

@@ -0,0 +1,208 @@
+---
+sidebar_label: To Remote Schema
+sidebar_position: 2
+description: Adding remote schema relationships with MS SQL Server tables in Hasura
+keywords:
+  - hasura
+  - docs
+  - remote schema relationship
+  - remote join
+  - remote schema
+  - data federation
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import Thumbnail from "@site/src/components/Thumbnail";
+import GraphiQLIDE from "@site/src/components/GraphiQLIDE";
+
+# MS SQL Server: Database to Remote Schema relationships
+
+## Introduction
+
+Database to Remote Schema relationships extend the concept of joining data across
+tables, to joining across tables and remote GraphQL sources. Once you
+create relationships between types from your database and types created
+from remote 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.
+
+:::info Note
+
+To see example use cases, check out this [blog
+post](https://hasura.io/blog/remote-joins-a-graphql-api-to-join-database-and-other-data-sources/).
+
+:::
+
+:::tip Supported from
+
+Remote schema relationships from MS SQL Server are supported from versions `v2.6.0` and
+above.
+
+:::
+
+## Create remote schema relationships
+
+### Step 0: Add a remote schema and a database
+
+Add a remote schema and a database as described [here](/graphql/core/remote-schemas/adding-schema.mdx)
+and [here](/graphql/core/databases/connect-db.mdx), if not already added.
+
+### Step 1: Define and create 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 example, let's assume that our database has a table
+`order(id int, user_id int)` and we've added a remote schema
+`user-remote-schema`.
+
+1.  We name the relationship `user`.
+2.  We select the `user-remote-schema` that we've added.
+3.  We set up the config to join the `id` input argument of our
+    remote schema field to the `user_id` column of this table (in this
+    case, the `order` table).
+
+<Tabs className="api-tabs">
+<TabItem value="console" label="Console">
+
+- Head to the `Data -> [table-name] -> Relationships` tab.
+- Click the `Add a remote relationship` button.
+
+  <Thumbnail
+    src="/img/graphql/core/schema/add-remote-schema-relationship.png"
+    alt="Opening the remote relationship section"
+    width="1000px"
+  />
+
+- Define the relationship and hit `Save`.
+
+  <Thumbnail
+    src="/img/graphql/core/schema/define-remote-schema-relationship.png"
+    alt="Defining the relationship"
+    width="800px"
+  />
+
+</TabItem>
+<TabItem value="cli" label="CLI">
+
+Update the `databases > [database-name] > tables > [table-name].yaml` file in the `metadata` directory:
+
+```yaml {4-13}
+- table:
+    schema: public
+    name: order
+  remote_relationships:
+  - name: user
+    definition:
+      remote_field:
+        user:
+          arguments:
+            id: $user_id
+      hasura_fields:
+        - user_id
+      remote_schema: user-remote-schema
+```
+
+Apply the metadata by running:
+
+```bash
+hasura metadata apply
+```
+
+</TabItem>
+<TabItem value="api" label="API">
+
+You can add a remote schema relationship by using the
+[pg_create_remote_relationship](/graphql/core/api-reference/metadata-api/remote-relationships.mdx#metadata-pg-create-remote-relationship) metadata API:
+
+```http
+POST /v1/metadata HTTP/1.1
+Content-Type: application/json
+X-Hasura-Role: admin
+
+{
+  "type":"mssql_create_remote_relationship",
+  "args": {
+    "name": "user",
+    "source": "mssql1",
+    "table": { "name": "order", "schema": "dbo" },
+    "hasura_fields": ["user_id"],
+    "remote_schema": "user-remote-schema",
+    "remote_field": {
+      "user": {
+        "arguments": {
+          "id": "$user_id"
+        }
+      }
+    }
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+### Step 2: Explore with GraphiQL
+
+In the GraphiQL tab, test out your remote schema relationship.
+
+<GraphiQLIDE
+  query={`query {
+  order {
+    id
+    user_id
+    user {
+      id
+      name
+    }
+  }
+}`}
+  response={`{
+  "data": {
+    "order": [
+      {
+        "id": 1,
+        "user_id": 2,
+        "user": {
+          "id": 2,
+          "name": "Bob"
+        }
+      }
+    ]
+  }
+}`}
+/>
+
+## Remote schema relationship permissions {#pg-remote-schema-relationship-permissions}
+
+Remote schema relationship permissions are derived from the
+[remote schema permissions](/graphql/core/remote-schemas/auth/remote-schema-permissions.mdx) defined for the
+role. When a remote relationship permission cannot be derived, the remote
+relationship field will not be added to the schema for the role.
+
+Some cases in which a remote relationship permission 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.
+
+:::info Note
+
+Remote relationship permissions apply only if remote schema permissions
+are enabled in GraphQL engine.
+
+:::

docs/docs/graphql/core/databases/ms-sql-server/schema/remote-relationships/remote-source-relationships.mdx

@@ -0,0 +1,198 @@
+---
+sidebar_label: To remote database
+sidebar_position: 1
+description: Adding remote database relationships with MS SQL Server tables in Hasura
+keywords:
+  - hasura
+  - docs
+  - remote database relationship
+  - remote join
+  - remote source
+  - data federation
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import Thumbnail from "@site/src/components/Thumbnail";
+import GraphiQLIDE from "@site/src/components/GraphiQLIDE";
+
+# MS SQL Server: Database to remote database relationships
+
+## Introduction
+
+Remote database relationships (a.k.a remote source relationships) extend the
+concept of joining data between tables within a single database to joining data
+across tables between separate databases.
+
+After you've established relationships between types in your source database and
+types in your target database, you can "join" them with GraphQL queries.
+
+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.
+
+:::tip Supported from
+
+Remote database relationships for MS SQL Server are supported from versions `v2.6.0` and above.
+
+:::
+
+## Create remote database relationships
+
+### Step 0: Add two database sources
+
+Add a source database as described [here](/graphql/core/databases/connect-db.mdx) and track the required tables.
+Then, repeat the process to add your target database.
+
+### Step 1: Define and create the relationship
+
+A remote database relationship is defined alongside the source database table (that is, the source side of the join).
+
+The following fields can be defined for a remote schema relationship:
+
+- **Relationship type**: Either `object` or `array` - similar to normal relationships. Hasura supports both many-to-one (object) and one-to-many (array) relationships.
+- **Relationship Name**: A name for the relationship.
+- **Reference Source**: The name of the target database (that is, the target side of the join).
+- **Reference Table**: The table in the target database source that should be joined with the source table
+- **Field Mapping**: A mapping between fields in the source table and their corresponding fields in the target table, just as a foreign key relationship would be defined by such mapping within a single database.
+
+For example, say we have a table `order(id int, user_id int)` in the source database and a table `user(id int, name text)` in the target database.
+
+We can create an object remote database relationship `user` joining the `order` table to the `user` table using the `order.user_id` and `user.id` fields.
+
+<Tabs className="api-tabs">
+<TabItem value="console" label="Console">
+
+Head to the `Data > [database] > [orders] > Relationships` tab.
+Under the `Remote Database Relationships` section, select `Add a remote database relationship`.
+
+<Thumbnail
+  src="/img/graphql/core/databases/ms-sql-server/schema/create-remote-source-relationship.png"
+  alt="Create remote database relationships"
+/>
+
+Hit `Save`.
+
+</TabItem>
+<TabItem value="cli" label="CLI">
+
+Update the `metadata > databases > [db-name] > tables > [public_orders].yaml` file:
+
+```yaml {4-14}
+table:
+  name: order
+  schema: public
+remote_relationships:
+- name: user
+  definition:
+    to_source:
+      relationship_type: object
+      source: pg2
+      table:
+        name: user
+        schema: public
+      field_mapping:
+        user_id: id
+```
+
+Apply the metadata:
+
+```bash
+hasura metadata apply
+```
+
+</TabItem>
+<TabItem value="api" label="API">
+
+You can add a remote database relationship by using the
+[mssql_create_remote_relationship](/graphql/core/api-reference/metadata-api/remote-relationships.mdx#metadata-mssql-create-remote-relationship) or
+[mssql_update_remote_relationship](/graphql/core/api-reference/metadata-api/remote-relationships.mdx#metadata-mssql-update-remote-relationship) metadata APIs with the `to_source` field.
+
+```http
+POST /v1/metadata HTTP/1.1
+Content-Type: application/json
+X-Hasura-Role: admin
+
+{
+  "type": "mssql_create_remote_relationship",
+  "args": {
+    "name": "user",
+    "source": "mssql1",
+    "table": {
+      "name": "order",
+      "schema": "public"
+    },
+    "definition": {
+      "to_source": {
+        "relationship_type": "object",
+        "source": "mssql2",
+        "table": {
+          "name": "user",
+          "schema": "public"
+        },
+        "field_mapping": {
+          "user_id": "id"
+        }
+      }
+    }
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+### Step 2: Explore with GraphiQL
+
+Run the following query in the GraphiQL editor to test your remote database relationship across the two connected databases:
+
+<GraphiQLIDE
+  query={`query {
+  order {
+    id
+    user_id
+    user {
+      id
+      name
+    }
+  }
+}`}
+  response={`{
+  "data": {
+    "order": [
+      {
+        "id": 1,
+        "user_id": 1,
+        "user": {
+          "id": 1,
+          "name": "Torvalds"
+        }
+      },
+      {
+        "id": 2,
+        "user_id": 2,
+        "user": {
+          "id": 2,
+          "name": "Zuckerberg"
+        }
+      },
+      {
+        "id": 3,
+        "user_id": 1,
+        "user": {
+          "id": 1,
+          "name": "Torvalds"
+        }
+      },
+      {
+        "id": 4,
+        "user_id": 3,
+        "user": {
+          "id": 3,
+          "name": "Gates"
+        }
+      }
+    ]
+  }
+}`}
+/>

docs/docs/graphql/core/databases/postgres/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Postgres",
-  "position": 1
+  "position": 2
 }

docs/docs/graphql/core/databases/postgres/schema/remote-relationships/action-relationships.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_label: Action relationships
+sidebar_label: From Action
 sidebar_position: 3
 description: Adding action relationships with Postgres tables in Hasura
 keywords:
@@ -14,7 +14,7 @@ import TabItem from "@theme/TabItem";
 import Thumbnail from "@site/src/components/Thumbnail";
 import GraphiQLIDE from "@site/src/components/GraphiQLIDE";
 
-# Postgres: Action relationships
+# Postgres: Action to database relationships
 
 ## Introduction
 
@@ -50,7 +50,9 @@ The following values can be defined for an action relationship:
   to.
 
 In this example, we're creating a relationship for the `createUser`
-action.
+action. We're creating a relationship called `user`, from the
+`id` field returned in the action response, to the `id` column of the
+`users` table.
 
 <Tabs className="api-tabs">
 <TabItem value="console" label="Console">
@@ -58,20 +60,20 @@ action.
 - Head to the `Actions -> [action-name] -> Relationships` tab.
 - Click `Add a relationship`.
 
-<Thumbnail
+  <Thumbnail
-  src="/img/graphql/core/schema/add-action-relationship.png"
+    src="/img/graphql/core/schema/add-action-relationship.png"
-  alt="Opening the action relationship section"
+    alt="Opening the action relationship section"
-  width="600px"
+    width="600px"
-/>
+  />
 
 - In the section opened by the above step, fill out the following
   fields and hit `Save`.
 
-<Thumbnail
+  <Thumbnail
-  src="/img/graphql/core/schema/define-action-relationship.png"
+    src="/img/graphql/core/schema/define-action-relationship.png"
-  alt="Defining the relationship"
+    alt="Defining the relationship"
-  width="700px"
+    width="700px"
-/>
+  />
 
 </TabItem>
 <TabItem value="cli" label="CLI">
@@ -143,10 +145,6 @@ X-Hasura-Role: admin
 </TabItem>
 </Tabs>
 
-In this example, we're creating a relationship called `user`, from the
-`id` field returned in the action response, to the `id` column of the
-`users` table.
-
 ### Step 2: Explore with GraphiQL
 
 In the GraphiQL tab, test out your action relationship.

docs/docs/graphql/core/databases/postgres/schema/remote-relationships/index.mdx

@@ -19,26 +19,27 @@ tables and remote data sources. The remote data source can either be a
 [remote schema](/graphql/core/remote-schemas/index.mdx), a table from a second database source,
 or the type returned from an [action](/graphql/core/actions/index.mdx). Once you create
 relationships between types from your database tables and types created
-from APIs or actions, you can then "join" them by running GraphQL
+from remote schemas or actions, you can then "join" them by running GraphQL
 queries.
 
 See the following guides on how to create different types of remote
-relationships:
+relationships related to Postgres:
-
-
-- [Remote database relationships](/graphql/core/databases/postgres/schema/remote-relationships/remote-source-relationships.mdx): To join data across tables between two different database sources, such as order information stored in a SQL Server database,
-  and user information stored in a separate Postgres database.
-- [Remote schema relationships](/graphql/core/databases/postgres/schema/remote-relationships/remote-schema-relationships.mdx): To join data across tables and remote GraphQL APIs, such as custom GraphQL servers you write, third party SaaS APIs,
-  or even other Hasura instances. For example, you can join customer data from your tables with account data from Stripe, Spotify, or Auth0.
-- [Action relationships](/graphql/core/databases/postgres/schema/remote-relationships/action-relationships.mdx): To join data across tables and actions (i.e. Rest APIs).
-  For example, you can join `user` data from your database with the response from a `createUser` action, using the `id` field.
 
+- [Database to database relationships](/graphql/core/databases/postgres/schema/remote-relationships/remote-source-relationships.mdx): To join
+data across tables between two different database sources, such as order information stored in a Postgres database, and user information stored
+in a separate Postgres or say a SQL Server database.
+- [Database to Remote Schema relationships](/graphql/core/databases/postgres/schema/remote-relationships/remote-schema-relationships.mdx): To
+join data across tables and remote GraphQL APIs. For example, you can join customer data from your tables with account data from Stripe, Spotify, or Auth0.
+- [Remote Schema to database relationships](/graphql/core/remote-schemas/remote-relationships/remote-schema-db-relationships.mdx): To join
+data from your remote schemas (such as Stripe, Spotify or Auth0) to customer data from your tables.
+- [Action to database relationships](/graphql/core/databases/postgres/schema/remote-relationships/action-relationships.mdx): To join data across
+tables and actions (i.e. Rest APIs). For example, you can join `user` data from your database with the response from a `createUser` action,
+using the `id` field.
 
 ## Benefits
 
 Hasura's remote joins architecture provides the following benefits.
 
-
 - **Security**: Hasura's [authorization model](/graphql/core/auth/authorization/index.mdx) gives
   you role-based access control. This extends to actions and remote
   schemas as well. In actions, you can go to the `Permissions` tab and

docs/docs/graphql/core/databases/postgres/schema/remote-relationships/remote-schema-relationships.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_label: Remote schema relationships
+sidebar_label: To Remote Schema
 sidebar_position: 2
 description: Adding remote schema relationships with Postgres tables in Hasura
 keywords:
@@ -16,14 +16,14 @@ import TabItem from "@theme/TabItem";
 import Thumbnail from "@site/src/components/Thumbnail";
 import GraphiQLIDE from "@site/src/components/GraphiQLIDE";
 
-# Postgres: Remote schema relationships
+# Postgres: Database to Remote Schema relationships
 
 ## Introduction
 
-Remote schema relationships extend the concept of joining data across
+Database to Remote Schema relationships extend the concept of joining data across
-tables, to joining across tables and remote data sources. Once you
+tables, to joining across tables and remote GraphQL sources. Once you
 create relationships between types from your database and types created
-from APIs, you can then "join" them by running GraphQL queries.
+from remote 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.
@@ -41,17 +41,17 @@ post](https://hasura.io/blog/remote-joins-a-graphql-api-to-join-database-and-oth
 
 :::tip Supported from
 
-Remote schema relationships are supported from versions `v1.3.0` and
+Remote schema relationships from Postgres are supported from versions `v1.3.0` and
 above.
 
 :::
 
 ## Create remote schema relationships
 
-### Step 0: Add a remote schema
+### Step 0: Add a remote schema and a database
 
-Add a remote schema as described [here](/graphql/core/remote-schemas/adding-schema.mdx), if the schema
+Add a remote schema and a database as described [here](/graphql/core/remote-schemas/adding-schema.mdx)
-isn't already added.
+and [here](/graphql/core/databases/connect-db.mdx), if not already added.
 
 ### Step 1: Define and create the relationship
 
@@ -67,15 +67,14 @@ The following fields can be defined for a remote schema relationship:
     your choice.
 
 For example, let's assume that our database has a table
-`users(name text, auth0_id text)` and we've added a remote schema
+`order(id int, user_id int)` and we've added a remote schema
-`authh0` which is a wrapper around [Auth0](https://auth0.com/)'s REST API (see example
+`user-remote-schema`.
-[here](https://github.com/hasura/graphql-engine/tree/master/community/boilerplates/remote-schemas/auth0-wrapper)).
 
-1.  We name the relationship `auth0_profile`.
+1.  We name the relationship `user`.
-2.  We select the `auth0` schema that we've added.
+2.  We select the `user-remote-schema` that we've added.
-3.  We set up the config to join the `auth0_id` input argument of our
+3.  We set up the config to join the `id` input argument of our
-    remote schema field to the `auth0_id` column of this table (in this
+    remote schema field to the `user_id` column of this table (in this
-    case, the `users` table).
+    case, the `order` table).
 
 <Tabs className="api-tabs">
 <TabItem value="console" label="Console">
@@ -83,19 +82,19 @@ For example, let's assume that our database has a table
 - Head to the `Data -> [table-name] -> Relationships` tab.
 - Click the `Add a remote relationship` button.
 
-<Thumbnail
+  <Thumbnail
-  src="/img/graphql/core/schema/add-remote-schema-relationship.png"
+    src="/img/graphql/core/schema/add-remote-schema-relationship.png"
-  alt="Opening the remote relationship section"
+    alt="Opening the remote relationship section"
-  width="1000px"
+    width="1000px"
-/>
+  />
 
 - Define the relationship and hit `Save`.
 
-<Thumbnail
+  <Thumbnail
-  src="/img/graphql/core/schema/define-remote-schema-relationship.png"
+    src="/img/graphql/core/schema/define-remote-schema-relationship.png"
-  alt="Defining the relationship"
+    alt="Defining the relationship"
-  width="800px"
+    width="800px"
-/>
+  />
 
 </TabItem>
 <TabItem value="cli" label="CLI">
@@ -105,17 +104,17 @@ Update the `databases > [database-name] > tables > [table-name].yaml` file in th
 ```yaml {4-13}
 - table:
     schema: public
-    name: users
+    name: order
   remote_relationships:
-  - name: auth0_profile
+  - name: user
     definition:
-      hasura_fields:
-        - auth0_id
-      remote_schema: auth0
       remote_field:
-        auth0:
+        user:
           arguments:
-            auth0_id: $auth0_id
+            id: $user_id
+      hasura_fields:
+        - user_id
+      remote_schema: user-remote-schema
 ```
 
 Apply the metadata by running:
@@ -138,17 +137,15 @@ X-Hasura-Role: admin
 {
   "type": "pg_create_remote_relationship",
   "args": {
-    "name": "auth0_profile",
+    "name": "user",
-    "source": "<db_name>",
+    "source": "pg1",
-    "table": "users",
+    "table": { "name": "order", "schema": "public" },
-    "hasura_fields": [
+    "hasura_fields": ["user_id"],
-      "auth0_id"
+    "remote_schema": "user-remote-schema",
-    ],
-    "remote_schema": "auth0",
     "remote_field": {
-      "auth0": {
+      "user": {
         "arguments": {
-          "auth0_id": "$auth0_id"
+          "id": "$user_id"
         }
       }
     }
@@ -165,26 +162,24 @@ In the GraphiQL tab, test out your remote schema relationship.
 
 <GraphiQLIDE
   query={`query {
-  users {
+  order {
-    name
+    id
-    auth0_id
+    user_id
-    auth0_profile {
+    user {
-      nickname
+      id
-      email
+      name
-      last_login
     }
   }
 }`}
   response={`{
   "data": {
-    "users": [
+    "order": [
       {
-        "name": "Daenerys Targaryen",
+        "id": 1,
-        "auth0_id": "auth0|507f1f77bcf86cd799439020",
+        "user_id": 2,
-        "auth0_profile": {
+        "user": {
-          "nickname": "Stormborn",
+          "id": 2,
-          "email": "mother.of.dragons@unburnt.com",
+          "name": "Bob"
-          "last_login": "2019-05-19T01:35:48.863Z"
         }
       }
     ]
@@ -196,10 +191,10 @@ In the GraphiQL tab, test out your remote schema relationship.
 
 Remote schema relationship permissions are derived from the
 [remote schema permissions](/graphql/core/remote-schemas/auth/remote-schema-permissions.mdx) defined for the
-role. When a remote relationship cannot be derived, the remote
+role. When a remote relationship permission 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:
+Some cases in which a remote relationship permission 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
@@ -208,6 +203,6 @@ Some of the cases in which a remote relationship cannot be derived are:
 :::info Note
 
 Remote relationship permissions apply only if remote schema permissions
-are enabled in graphql-engine.
+are enabled in GraphQL engine.
 
 :::

docs/docs/graphql/core/databases/postgres/schema/remote-relationships/remote-source-relationships.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_label: Remote database relationships
+sidebar_label: To remote database
 sidebar_position: 1
 description: Adding remote database relationships with Postgres tables in Hasura
 keywords:
@@ -16,17 +16,24 @@ import TabItem from '@theme/TabItem';
 import Thumbnail from "@site/src/components/Thumbnail";
 import GraphiQLIDE from "@site/src/components/GraphiQLIDE";
 
-# Postgres: Remote database relationships
+# Postgres: Database to remote database relationships
 
 ## Introduction
 
-Remote database relationships (a.k.a remote source relationships) extend the concept of joining data between tables within a single database to joining data across tables between separate databases.
+Remote database relationships (a.k.a remote source relationships) extend the
+concept of joining data between tables within a single database to joining data
+across tables between separate databases.
 
-After you've established relationships between types in your source database and types in your target database, you can "join" them with GraphQL queries.
+After you've established relationships between types in your source database and
+types in your target database, you can "join" them with GraphQL queries.
+
+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.
 
 :::tip Supported from
 
-Remote database relationships are supported from versions `v2.1.0` and above.
+Remote database relationships for Postgres are supported from versions `v2.1.0` and above.
 
 :::
 
@@ -45,13 +52,13 @@ The following fields can be defined for a remote schema relationship:
 
 - **Relationship type**: Either `object` or `array` - similar to normal relationships. Hasura supports both many-to-one (object) and one-to-many (array) relationships.
 - **Relationship Name**: A name for the relationship.
-- **Reference Source**: The name of the target database (that is, the target side of the join)
+- **Reference Source**: The name of the target database (that is, the target side of the join).
 - **Reference Table**: The table in the target database source that should be joined with the source table
 - **Field Mapping**: A mapping between fields in the source table and their corresponding fields in the target table, just as a foreign key relationship would be defined by such mapping within a single database.
 
-For example, say we have a table `orders(id int, order_user_id int)` in the source database and a table `users(id int, name text)` in the target database.
+For example, say we have a table `order(id int, user_id int)` in the source database and a table `user(id int, name text)` in the target database.
 
-We can create an object remote database relationship `order_user` joining the `orders` table to the `users` table using the `orders.order_user_id` and `users.id` fields.
+We can create an object remote database relationship `user` joining the `order` table to the `user` table using the `order.user_id` and `user.id` fields.
 
 <Tabs className="api-tabs">
 <TabItem value="console" label="Console">
@@ -73,19 +80,19 @@ Update the `metadata > databases > [db-name] > tables > [public_orders].yaml` fi
 
 ```yaml {4-14}
 table:
-  name: orders
+  name: order
   schema: public
 remote_relationships:
-- name: order_user
+- name: user
   definition:
     to_source:
       relationship_type: object
       source: pg2
       table:
-        name: users
+        name: user
         schema: public
       field_mapping:
-        order_user_id: id
+        user_id: id
 ```
 
 Apply the metadata:
@@ -109,10 +116,10 @@ X-Hasura-Role: admin
 {
   "type": "pg_create_remote_relationship",
   "args": {
-    "name": "order_user",
+    "name": "user",
     "source": "pg1",
     "table": {
-      "name": "orders",
+      "name": "order",
       "schema": "public"
     },
     "definition": {
@@ -120,11 +127,11 @@ X-Hasura-Role: admin
         "relationship_type": "object",
         "source": "pg2",
         "table": {
-          "name": "users",
+          "name": "user",
           "schema": "public"
         },
         "field_mapping": {
-          "order_user_id": "id"
+          "user_id": "id"
         }
       }
     }
@@ -141,10 +148,10 @@ Run the following query in the GraphiQL editor to test your remote database rela
 
 <GraphiQLIDE
   query={`query {
-  orders {
+  order {
     id
-    order_user_id
+    user_id
-    order_user {
+    user {
       id
       name
     }
@@ -152,35 +159,35 @@ Run the following query in the GraphiQL editor to test your remote database rela
 }`}
   response={`{
   "data": {
-    "orders": [
+    "order": [
       {
         "id": 1,
-        "order_user_id": 1,
+        "user_id": 1,
-        "order_user": {
+        "user": {
-          "user_id": 1,
+          "id": 1,
           "name": "Torvalds"
         }
       },
       {
         "id": 2,
-        "order_user_id": 2,
+        "user_id": 2,
-        "order_user": {
+        "user": {
           "id": 2,
           "name": "Zuckerberg"
         }
       },
       {
         "id": 3,
-        "order_user_id": 1,
+        "user_id": 1,
-        "order_user": {
+        "user": {
           "id": 1,
           "name": "Torvalds"
         }
       },
       {
         "id": 4,
-        "order_user_id": 3,
+        "user_id": 3,
-        "order_user": {
+        "user": {
           "id": 3,
           "name": "Gates"
         }

docs/docs/graphql/core/faq.mdx

@@ -4,7 +4,7 @@ keywords:
   - hasura
   - docs
   - FAQs
-sidebar_position: 14
+sidebar_position: 15
 sidebar_label: FAQs
 # adding to avoid redirect as this was only index file under the directory
 slug: faq/index

docs/docs/graphql/core/guides/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Guides / Tutorials / Resources",
-  "position": 15
+  "position": 17
 }

docs/docs/graphql/core/remote-schemas/adding-schema.mdx

@@ -12,19 +12,19 @@ import Thumbnail from "@site/src/components/Thumbnail";
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-# Adding a remote schema
+# Adding a Remote Schema
 
 ## Introduction
 
-Follow the steps below to merge your remote schema with the GraphQL engine's auto-generated schema.
+Follow the steps below to merge your remote GraphQL API with the GraphQL engine's auto-generated API.
 
 ## Step 0: Write a custom GraphQL server
 
-*If you already have a functional GraphQL server that meets your requirements, you can skip this step.*
+*You can skip this step if you are using a 3rd party GraphQL API or already have a functional GraphQL server that meets your requirements.*
 
-You need to create a custom GraphQL server with a schema and corresponding resolvers that solve your use case
+You need to create a custom GraphQL server with a schema and corresponding resolvers that solve your use case.
 
-You can use any language/framework of your choice to author this server and deploy it anywhere. A great way to get started is to use one of our [boilerplates](https://github.com/hasura/graphql-engine/tree/master/community/boilerplates/remote-schemas)
+You can use any language/framework of your choice to author this server and deploy it anywhere. A great way to get started is to use one of our [boilerplates](https://github.com/hasura/graphql-engine/tree/master/community/boilerplates/remote-schemas).
 
 ## Step 1: Merge remote schema {#merge-remote-schema}
 

docs/docs/graphql/core/remote-schemas/auth/_category_.json

@@ -1,3 +1,4 @@
 {
-  "label": "Authorization in remote schemas"
+  "label": "Authorization in remote schemas",
+  "position": 4
 }

docs/docs/graphql/core/remote-schemas/index.mdx

@@ -49,7 +49,7 @@ Hasura Cloud offers built-in API metrics with integrated health checks and distr
 ## Learn more
 
 - [Adding a remote schema](/graphql/core/remote-schemas/adding-schema.mdx)
-- [Remote schema relationships](/graphql/core/remote-schemas/remote-schema-relationships.mdx)
+- [Remote relationships](/graphql/core/remote-schemas/remote-relationships/index.mdx)
 - [Authorization in remote schemas](/graphql/core/remote-schemas/auth/index.mdx)
 
 :::info Additional Resources

docs/docs/graphql/core/remote-schemas/remote-relationships/_category_.json

@@ -0,0 +1,5 @@
+{
+    "label": "Remote relationships",
+    "position": 3
+}
+  

docs/docs/graphql/core/remote-schemas/remote-relationships/index.mdx

@@ -0,0 +1,69 @@
+---
+slug: index
+description: Manage remote relationships in Hasura
+keywords:
+  - hasura
+  - docs
+  - schema
+  - relationship
+  - remote relationship
+---
+
+# Remote relationships
+
+## Introduction
+
+Remote relationships (aka "remote joins") allow you to join data across
+remote schemas and other remote data sources. The remote data source can either be another
+[remote schema](/graphql/core/remote-schemas/index.mdx) or a table from a database source.
+Once you create relationships between types from your remote schema and types created
+from databases or other remote schemas, you can then "join" them by running GraphQL
+queries.
+
+See the following guides on how to create different types of remote
+relationships related to remote schemas:
+
+- [Remote Schema to database relationships](/graphql/core/remote-schemas/remote-relationships/remote-schema-db-relationships.mdx): To join
+data from your remote schemas (such as Stripe, Spotify or Auth0) to customer data from your tables.
+- [Remote Schema to Remote Schema relationships](/graphql/core/remote-schemas/remote-relationships/remote-schema-relationships.mdx): To
+join data between two remote schemas such as Stripe, Spotify or Auth0 to customer data from your custom GraphQL API.
+- [Database to Remote Schema relationships](/graphql/core/databases/postgres/schema/remote-relationships/remote-schema-relationships.mdx): To
+join data across tables and remote GraphQL APIs. For example, you can join customer data from your tables with account data from Stripe, Spotify, or Auth0.
+
+## Benefits
+
+Hasura's remote joins architecture provides the following benefits.
+
+
+- **Security**: Hasura's [authorization model](/graphql/core/auth/authorization/index.mdx) gives
+  you role-based access control. This extends to actions and remote
+  schemas as well. In actions, you can go to the `Permissions` tab and
+  choose which fields to expose for which roles. For remote schemas,
+  Hasura will [forward your session variables](/graphql/core/remote-schemas/auth/index.mdx)
+  which can be used to implement custom authorization in your remote
+  schemas. Native role-based permissions on remote schemas is in the
+  works.
+- **Performance**: Hasura strives for optimal performance. It creates
+  an efficient execution plan which pushes down most of the
+  heavy-lifting involved to underlying sources. For example, Hasura
+  creates a single efficient query to your database and batches calls
+  to remote schemas to avoid the [n+1
+  problem](https://hasura.io/learn/graphql/intro-graphql/graphql-server/)
+  . More improvements to performance are upcoming.
+- **Schema integrity & consistency**: Hasura has metadata consistency
+  checks at every level. Whenever you add a table, remote schema, or
+  action, Hasura makes sure that the graph that is exposed is
+  consistent, and that all the relationships make sense at a type
+  level. This helps you in creating robust workflows to test changes
+  in your CI and making safe deployments of your unified graph.
+- **Data federation**: With remote joins, the join, authorization, and
+  consistency checks of added sources all happen at the Hasura layer
+  via metadata. This allows underlying data sources and APIs to evolve
+  independently. Your applications have a unified API to query the
+  full data landscape in your org.
+
+:::info Additional Resources
+
+Data Federation with Hasura - [Watch Webinar](https://hasura.io/events/webinar/data-federation-hasura-graphql/?pg=docs&plcmt=body&cta=watch-webinar&tech=).
+
+:::

docs/docs/graphql/core/remote-schemas/remote-relationships/remote-schema-db-relationships.mdx

@@ -0,0 +1,183 @@
+---
+sidebar_label: To remote database
+sidebar_position: 2
+description: Adding remote schema relationships with Postgres tables in Hasura
+keywords:
+  - hasura
+  - docs
+  - remote schema relationship
+  - remote join
+  - remote schema
+  - data federation
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import Thumbnail from "@site/src/components/Thumbnail";
+import GraphiQLIDE from "@site/src/components/GraphiQLIDE";
+
+# Remote Schema to database relationships
+
+## Introduction
+
+Remote schema to database relationships extend the concept of joining data across
+tables, to joining across tables and remote GraphQL sources. Once you
+create relationships between types from your database and types created
+from the remote schema, you can then "join" them by running GraphQL queries.
+
+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.
+
+:::tip Supported from
+
+Relationships from remote schema to database are supported from versions `v2.6.0` and above.
+
+:::
+
+## Create remote schema relationships
+
+### Step 0: Add a remote schema and a database
+
+Add a remote schema and a database as described [here](/graphql/core/remote-schemas/adding-schema.mdx)
+and [here](/graphql/core/databases/connect-db.mdx), if not already added.
+
+### Step 1: Define and create 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 example, let's assume that our database has a table
+`user(id integer, name text)` and we've added a remote schema
+`order-remote-schema` which is another GraphQL API. Now we want to create a relationship between the `order` field
+of the remote schema and the `user` table of the source database.
+
+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 `pg1` as the reference database, `public` as the reference schema and `user` as the reference table.
+4.  We select `user_id` as the source field and `id` as the reference column.
+
+<Tabs className="api-tabs">
+<TabItem value="console" label="Console">
+
+- Head to the `Remote schema -> [remote-schema-name] -> Relationships` tab.
+- Click the `Add a new relationship` button.
+
+  <Thumbnail
+    src="/img/graphql/core/schema/create-relationship-from-remote-schema.png"
+    alt="Opening the remote relationship section"
+    width="1000px"
+  />
+
+- Define the relationship and hit `Add Relationship`.
+
+  <Thumbnail
+    src="/img/graphql/core/schema/configure-relationship-rs-to-db.png"
+    alt="Defining the relationship"
+    width="800px"
+  />
+
+</TabItem>
+<TabItem value="cli" label="CLI">
+
+Update the `remote_schemas.yaml` file in the `metadata` directory:
+
+```yaml {4-15}
+- name: order-remote-schema
+  definition:
+    url: https://remote-schema-endpoint.com
+  remote_relationships:
+    - relationships:
+        - name: user
+          definition:
+            to_source:
+              relationship_type: object
+              source: pg1
+              table:
+                schema: public
+                name: user
+              field_mapping:
+                user_id: id
+```
+
+Apply the metadata by running:
+
+```bash
+hasura metadata apply
+```
+
+</TabItem>
+<TabItem value="api" label="API">
+
+You can add a remote schema relationship by using the
+[create_remote_schema_remote_relationship](/graphql/core/api-reference/metadata-api/remote-relationships.mdx#metadata-create-remote-schema-remote-relationship) metadata API and update it by using the [update_remote_schema_remote_relationship](/graphql/core/api-reference/metadata-api/remote-relationships.mdx#metadata-update-remote-schema-remote-relationship) metadata API:
+
+```http
+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_source": {
+        "relationship_type": "object",
+        "source": "pg1",
+        "table": { "name": "user", "schema": "public" },
+        "field_mapping": {
+          "user_id": "id"
+        }
+      }
+    }
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+### Step 2: Explore with GraphiQL
+
+In the GraphiQL tab, test out your remote schema relationship.
+
+<GraphiQLIDE
+  query={`query {
+  order_remote_schema {
+  	order (id: 1) {
+    	id
+    	user_id
+    	user {
+      	id
+        name
+    	}
+  	}
+  }
+}`}
+  response={`{
+  "data": {
+    "order_remote_schema": {
+      "order": {
+        "id": 1,
+        "user_id": 2,
+        "user": {
+          "id": 2,
+          "name": "Bob"
+        }
+      }
+    }
+  }
+}`}
+/>
+

docs/docs/graphql/core/remote-schemas/remote-relationships/remote-schema-relationships.mdx

@@ -0,0 +1,190 @@
+---
+sidebar_label: To Remote Schema
+sidebar_position: 3
+description: Adding remote schema relationships with Postgres tables in Hasura
+keywords:
+  - hasura
+  - docs
+  - remote schema relationship
+  - remote join
+  - graphql join
+  - remote schema
+  - data federation
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import Thumbnail from "@site/src/components/Thumbnail";
+import GraphiQLIDE from "@site/src/components/GraphiQLIDE";
+
+# 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.
+
+:::tip Supported from
+
+Relationships from remote schema to remote schema are supported from versions `v2.6.0` and above.
+
+:::
+
+## Create remote schema relationships
+
+### Step 0: Add two remote schemas
+
+Add two remote schemas as described [here](/graphql/core/remote-schemas/adding-schema.mdx), if the schemas
+aren't already added.
+
+### Step 1: 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.
+
+<Tabs className="api-tabs">
+<TabItem value="console" label="Console">
+
+- Head to the `Remote schema -> [remote-schema-name] -> Relationships` tab.
+- Click the `Add a new relationship` button.
+
+  <Thumbnail
+    src="/img/graphql/core/schema/create-relationship-from-remote-schema.png"
+    alt="Opening the remote relationship section"
+    width="1000px"
+  />
+
+- Define the relationship and hit `Add Relationship`.
+
+  <Thumbnail
+    src="/img/graphql/core/schema/configure-relationship-rs-to-rs.png"
+    alt="Defining the relationship"
+    width="800px"
+  />
+
+</TabItem>
+<TabItem value="cli" label="CLI">
+
+Update the `remote_schemas.yaml` file in the `metadata` directory:
+
+```yaml {4-16}
+- 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:
+
+```bash
+hasura metadata apply
+```
+
+</TabItem>
+<TabItem value="api" label="API">
+
+You can add a remote schema relationship by using the
+[create_remote_schema_remote_relationship](/graphql/core/api-reference/metadata-api/remote-relationships.mdx#metadata-create-remote-schema-remote-relationship) metadata API and update it by using the [update_remote_schema_remote_relationship](/graphql/core/api-reference/metadata-api/remote-relationships.mdx#metadata-update-remote-schema-remote-relationship) metadata API:
+
+```http
+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"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+### Step 2: Explore with GraphiQL
+
+In the GraphiQL tab, test out your remote schema relationship.
+
+<GraphiQLIDE
+  query={`query {
+  order_remote_schema {
+  	order (id: 1) {
+    	id
+    	user_id
+    	user {
+      	id
+      	name
+    	}
+  	}
+  }
+}`}
+  response={`{
+  "data": {
+    "order_remote_schema": {
+      "order": {
+        "id": 1,
+        "user_id": 2,
+        "user": {
+          "id": 2,
+          "name": "Bob"
+        }
+      }
+    }
+  }
+}`}
+/>

docs/docs/graphql/core/remote-schemas/remote-schema-relationships.mdx

@@ -1,25 +0,0 @@
----
-description: Manage remote schema relationships with Hasura
-keywords:
-  - hasura
-  - docs
-  - remote schema
-  - relationships
-sidebar_position: 3
----
-
-# Remote schema relationships
-
-## Introduction
-
-You can create remote relationships between your tables/views and fields from your remote schema.
-
-Read more about this at:
-
-- [Postgres: Remote schema relationships](/graphql/core/databases/postgres/schema/remote-relationships/remote-schema-relationships.mdx)
-
-:::info Additional Resources
-
-Data Federation with Hasura - [Watch Webinar](https://hasura.io/events/webinar/data-federation-hasura-graphql/?pg=docs&plcmt=body&cta=watch-webinar&tech=).
-
-:::

docs/docs/graphql/core/troubleshooting.mdx

@@ -1,6 +1,6 @@
 ---
 sidebar_label: Troubleshooting
-sidebar_position: 13
+sidebar_position: 14
 description: Troubleshoot Hasura GraphQL engine errors
 keywords:
   - hasura