mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-15 01:12:56 +03:00
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
This commit is contained in:
Marion Schleifer
hasura-bot
parent
88f8c676d4
commit
0d66c316ce
46
docs/docs/graphql/core/data-federation.mdx
Normal file
46
docs/docs/graphql/core/data-federation.mdx
Normal file
@ -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.
|
||||
@ -1,4 +1,4 @@
|
||||
{
|
||||
"label": "BigQuery",
|
||||
"position": 4
|
||||
"position": 5
|
||||
}
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
{
|
||||
"label": "Citus / Hyperscale",
|
||||
"position": 3
|
||||
"position": 4
|
||||
}
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
sidebar_label: Connecting databases
|
||||
sidebar_position: 5
|
||||
sidebar_position: 1
|
||||
description: Connect a database to Hasura
|
||||
keywords:
|
||||
- hasura
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
{
|
||||
"label": "MS SQL Server",
|
||||
"position": 2
|
||||
"position": 3
|
||||
}
|
||||
|
||||
@ -0,0 +1,4 @@
|
||||
{
|
||||
"label": "Remote relationships",
|
||||
"position": 3
|
||||
}
|
||||
@ -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.
|
||||
@ -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.
|
||||
|
||||
:::
|
||||
@ -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"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}`}
|
||||
/>
|
||||
@ -1,4 +1,4 @@
|
||||
{
|
||||
"label": "Postgres",
|
||||
"position": 1
|
||||
"position": 2
|
||||
}
|
||||
@ -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
|
||||
src="/img/graphql/core/schema/add-action-relationship.png"
|
||||
alt="Opening the action relationship section"
|
||||
width="600px"
|
||||
/>
|
||||
<Thumbnail
|
||||
src="/img/graphql/core/schema/add-action-relationship.png"
|
||||
alt="Opening the action relationship section"
|
||||
width="600px"
|
||||
/>
|
||||
|
||||
- In the section opened by the above step, fill out the following
|
||||
fields and hit `Save`.
|
||||
|
||||
<Thumbnail
|
||||
src="/img/graphql/core/schema/define-action-relationship.png"
|
||||
alt="Defining the relationship"
|
||||
width="700px"
|
||||
/>
|
||||
<Thumbnail
|
||||
src="/img/graphql/core/schema/define-action-relationship.png"
|
||||
alt="Defining the relationship"
|
||||
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.
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
- [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.
|
||||
relationships related to Postgres:
|
||||
|
||||
- [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
|
||||
|
||||
@ -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
|
||||
tables, to joining across tables and remote data sources. Once you
|
||||
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 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
|
||||
isn't already added.
|
||||
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
|
||||
|
||||
@ -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
|
||||
`authh0` which is a wrapper around [Auth0](https://auth0.com/)'s REST API (see example
|
||||
[here](https://github.com/hasura/graphql-engine/tree/master/community/boilerplates/remote-schemas/auth0-wrapper)).
|
||||
`order(id int, user_id int)` and we've added a remote schema
|
||||
`user-remote-schema`.
|
||||
|
||||
1. We name the relationship `auth0_profile`.
|
||||
2. We select the `auth0` schema that we've added.
|
||||
3. We set up the config to join the `auth0_id` input argument of our
|
||||
remote schema field to the `auth0_id` column of this table (in this
|
||||
case, the `users` table).
|
||||
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">
|
||||
@ -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
|
||||
src="/img/graphql/core/schema/add-remote-schema-relationship.png"
|
||||
alt="Opening the remote relationship section"
|
||||
width="1000px"
|
||||
/>
|
||||
<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"
|
||||
/>
|
||||
<Thumbnail
|
||||
src="/img/graphql/core/schema/define-remote-schema-relationship.png"
|
||||
alt="Defining the relationship"
|
||||
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",
|
||||
"source": "<db_name>",
|
||||
"table": "users",
|
||||
"hasura_fields": [
|
||||
"auth0_id"
|
||||
],
|
||||
"remote_schema": "auth0",
|
||||
"name": "user",
|
||||
"source": "pg1",
|
||||
"table": { "name": "order", "schema": "public" },
|
||||
"hasura_fields": ["user_id"],
|
||||
"remote_schema": "user-remote-schema",
|
||||
"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 {
|
||||
name
|
||||
auth0_id
|
||||
auth0_profile {
|
||||
nickname
|
||||
email
|
||||
last_login
|
||||
order {
|
||||
id
|
||||
user_id
|
||||
user {
|
||||
id
|
||||
name
|
||||
}
|
||||
}
|
||||
}`}
|
||||
response={`{
|
||||
"data": {
|
||||
"users": [
|
||||
"order": [
|
||||
{
|
||||
"name": "Daenerys Targaryen",
|
||||
"auth0_id": "auth0|507f1f77bcf86cd799439020",
|
||||
"auth0_profile": {
|
||||
"nickname": "Stormborn",
|
||||
"email": "mother.of.dragons@unburnt.com",
|
||||
"last_login": "2019-05-19T01:35:48.863Z"
|
||||
"id": 1,
|
||||
"user_id": 2,
|
||||
"user": {
|
||||
"id": 2,
|
||||
"name": "Bob"
|
||||
}
|
||||
}
|
||||
]
|
||||
@ -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.
|
||||
|
||||
:::
|
||||
|
||||
@ -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
|
||||
order_user {
|
||||
user_id
|
||||
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,
|
||||
"order_user": {
|
||||
"user_id": 1,
|
||||
"user_id": 1,
|
||||
"user": {
|
||||
"id": 1,
|
||||
"name": "Torvalds"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"order_user_id": 2,
|
||||
"order_user": {
|
||||
"user_id": 2,
|
||||
"user": {
|
||||
"id": 2,
|
||||
"name": "Zuckerberg"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"order_user_id": 1,
|
||||
"order_user": {
|
||||
"user_id": 1,
|
||||
"user": {
|
||||
"id": 1,
|
||||
"name": "Torvalds"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"order_user_id": 3,
|
||||
"order_user": {
|
||||
"user_id": 3,
|
||||
"user": {
|
||||
"id": 3,
|
||||
"name": "Gates"
|
||||
}
|
||||
|
||||
@ -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
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
{
|
||||
"label": "Guides / Tutorials / Resources",
|
||||
"position": 15
|
||||
"position": 17
|
||||
}
|
||||
@ -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}
|
||||
|
||||
|
||||
@ -1,3 +1,4 @@
|
||||
{
|
||||
"label": "Authorization in remote schemas"
|
||||
"label": "Authorization in remote schemas",
|
||||
"position": 4
|
||||
}
|
||||
@ -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
|
||||
|
||||
@ -0,0 +1,5 @@
|
||||
{
|
||||
"label": "Remote relationships",
|
||||
"position": 3
|
||||
}
|
||||
|
||||
@ -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=).
|
||||
|
||||
:::
|
||||
@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}`}
|
||||
/>
|
||||
|
||||
@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}`}
|
||||
/>
|
||||
@ -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=).
|
||||
|
||||
:::
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
sidebar_label: Troubleshooting
|
||||
sidebar_position: 13
|
||||
sidebar_position: 14
|
||||
description: Troubleshoot Hasura GraphQL engine errors
|
||||
keywords:
|
||||
- hasura
|
||||
|
||||
BIN
docs/static/img/graphql/core/databases/ms-sql-server/schema/create-remote-source-relationship.png
vendored
Normal file
BIN
docs/static/img/graphql/core/databases/ms-sql-server/schema/create-remote-source-relationship.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 62 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 52 KiB After Width: | Height: | Size: 64 KiB |
BIN
docs/static/img/graphql/core/schema/configure-relationship-rs-to-db-mssql.png
vendored
Normal file
BIN
docs/static/img/graphql/core/schema/configure-relationship-rs-to-db-mssql.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
BIN
docs/static/img/graphql/core/schema/configure-relationship-rs-to-db.png
vendored
Normal file
BIN
docs/static/img/graphql/core/schema/configure-relationship-rs-to-db.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 51 KiB |
BIN
docs/static/img/graphql/core/schema/configure-relationship-rs-to-rs.png
vendored
Normal file
BIN
docs/static/img/graphql/core/schema/configure-relationship-rs-to-rs.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 63 KiB |
BIN
docs/static/img/graphql/core/schema/create-relationship-from-remote-schema.png
vendored
Normal file
BIN
docs/static/img/graphql/core/schema/create-relationship-from-remote-schema.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 53 KiB After Width: | Height: | Size: 20 KiB |
Loading…
Reference in New Issue
Block a user