docs(server): update table/NQ relationship docs

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/10188
Co-authored-by: Sean Park-Ross <94021366+seanparkross@users.noreply.github.com>
GitOrigin-RevId: 9335ff2704ff8ea900b3b8194ea02aedf7ee267b

docs/docs/schema/bigquery/logical-models.mdx

@@ -283,8 +283,6 @@ X-Hasura-Role: admin
 
 Logical Model fields are allowed to refer to other Logical Models, even recursively, allowing nested data types.
 
-Object or array relationships between Native Queries are an example use of this.
-
 To elaborate on the `article` example above, we can include authors in the data model:
 
 <Tabs groupId="user-preference" className="api-tabs">

docs/docs/schema/bigquery/native-queries.mdx

@@ -531,7 +531,7 @@ Unlike tables, relationships for a Native Query have to be given as part of trac
 Native Query is defined by its Logical Model, and the Native Query needs to implement all the fields of the Logical
 Model in order to be tracked successfully.
 
-Currently relationships are only supported between Native Queries residing in the same source.
+Currently relationships are only supported between Native Queries and tables residing in the same source.
 
 As an example, consider the following Native Queries which implement the data model of articles and authors given in the
 section on [Logical Model references](/schema/bigquery/logical-models.mdx#referencing-other-logical-models):
@@ -566,13 +566,6 @@ X-Hasura-Role: admin
             "name": "author_id",
             "nullable": false,
             "type": "INT64"
-          },
-          {
-            "name": "author",
-            "type": {
-              "logical_model": "author",
-              "nullable": false
-            }
           }
         ],
         "name": "article",
@@ -593,15 +586,6 @@ X-Hasura-Role: admin
             "name": "name",
             "nullable": false,
             "type": "VARCHAR"
-          },
-          {
-            "name": "articles",
-            "type": {
-              "array": {
-                "logical_model": "article"
-              },
-              "nullable": false
-            }
           }
         ],
         "name": "author",
@@ -694,3 +678,94 @@ query {
 
 </TabItem>
 </Tabs>
+
+
+## Relationships with tables
+
+Relationships can be defined between tables and Native Queries residing in the same source.
+
+As an example, given a table `authors`, consider the following definition of Logical Models and Native Queries:
+
+<Tabs groupId="user-preference" className="api-tabs">
+<TabItem value="api" label="API">
+
+```http
+POST /v1/metadata HTTP/1.1
+Content-Type: application/json
+X-Hasura-Role: admin
+
+{
+  "type": "bulk_atomic",
+  "args": [
+    {
+      "type": "bigquery_track_logical_model",
+      "args": {
+        "description": "",
+        "fields": [
+          {
+            "name": "id",
+            "nullable": false,
+            "type": "integer"
+          },
+          {
+            "name": "title",
+            "nullable": false,
+            "type": "text"
+          },
+          {
+            "name": "author_id",
+            "nullable": false,
+            "type": "integer"
+          }
+        ],
+        "name": "article",
+        "source": "default"
+      }
+    }
+    {
+      "type": "bigquery_track_native_query",
+      "args": {
+        "arguments": {},
+        "array_relationships": [],
+        "code": "SELECT * FROM (VALUES (1, 'Logical Models', 1), (2, 'Native Queries', 2), (3, 'Relationships', 3), (4, 'Graph Relationships', 4), (5, 'Permissions', 5)) as t(\"id\", \"title\", \"author_id\")",
+        "object_relationships": [
+          {
+            "name": "author",
+            "using": {
+              "column_mapping": {
+                "author_id": "id"
+              },
+              "insertion_order": null,
+              "remote_table": "authors"
+            }
+          }
+        ],
+        "returns": "article",
+        "root_field_name": "get_articles",
+        "source": "default",
+        "type": "query"
+      }
+    }
+  ]
+}
+```
+
+</TabItem>
+<TabItem value="query" label="Query">
+
+The Native Queries in this example enable queries like:
+
+```graphql
+query {
+  get_articles {
+    title
+
+    author {
+      name
+    }
+  }
+}
+```
+
+</TabItem>
+</Tabs>

docs/docs/schema/bigquery/table-relationships/create.mdx

@@ -20,7 +20,7 @@ import TabItem from '@theme/TabItem';
 
 ## Introduction
 
-A relationship from one table to another can be created by defining a link between a column of the table to a column of
+A relationship from one table or Native Query to another can be created by defining a link between a column of the table to a column of
 the other table.
 
 Typically, relationships are defined using foreign-key constraints. Because BigQuery doesn't support a notion of primary
@@ -276,3 +276,46 @@ If we run the following query, we can see that we've now added an `articles` arr
 The query field will be of the format `<dataset_name>_<table_name>`.
 
 :::
+
+## Tracking relationships between tables and Native Queries
+
+As mentioned in the Introduction section above, a relationship from a table to a Native Query can only be set up manually.
+
+<Tabs groupId="user-preference" className="api-tabs">
+<TabItem value="api" label="API">
+
+Given a table named `articles` and an existing Native Query named `get_author`,
+we can set up a relationship between the two.
+
+```http
+POST /v1/metadata HTTP/1.1
+Content-Type: application/json
+X-Hasura-Role: admin
+
+{
+  "type": "bulk",
+  "args": [
+    {
+      "type": "bigquery_create_object_relationship",
+      "args": {
+        "source": "<db_name>",
+        "table": "articles",
+        "name": "author",
+        "using": {
+          "manual_configuration": {
+            "remote_native_query": "get_author",
+            "column_mapping": {
+              "id": "author_id"
+            }
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+</TabItem>
+</Tabs>
+
+

docs/docs/schema/ms-sql-server/logical-models.mdx

@@ -278,8 +278,6 @@ X-Hasura-Role: admin
 
 Logical Model fields are allowed to refer to other Logical Models, even recursively, allowing nested data types.
 
-Object or array relationships between Native Queries are an example use of this.
-
 To elaborate on the `article` example above, we can include authors in the data model:
 
 <Tabs groupId="user-preference" className="api-tabs">

docs/docs/schema/ms-sql-server/native-queries.mdx

@@ -541,7 +541,7 @@ Unlike tables, relationships for a Native Query have to be given as part of trac
 Native Query is defined by its Logical Model, and the Native Query needs to implement all the fields of the Logical
 Model in order to be tracked successfully.
 
-Currently relationships are only supported between Native Queries residing in the same source.
+Currently relationships are only supported between Native Queries and tables residing in the same source.
 
 As an example, consider the following Native Queries which implement the data model of articles and authors given in the
 section on [Logical Model references](/schema/ms-sql-server/logical-models.mdx#referencing-other-logical-models):
@@ -576,13 +576,6 @@ X-Hasura-Role: admin
             "name": "author_id",
             "nullable": false,
             "type": "integer"
-          },
-          {
-            "name": "author",
-            "type": {
-              "logical_model": "author",
-              "nullable": false
-            }
           }
         ],
         "name": "article",
@@ -603,15 +596,6 @@ X-Hasura-Role: admin
             "name": "name",
             "nullable": false,
             "type": "varchar"
-          },
-          {
-            "name": "articles",
-            "type": {
-              "array": {
-                "logical_model": "article"
-              },
-              "nullable": false
-            }
           }
         ],
         "name": "author",
@@ -704,3 +688,93 @@ query {
 
 </TabItem>
 </Tabs>
+
+## Relationships with tables
+
+Relationships can be defined between tables and Native Queries residing in the same source.
+
+As an example, given a table `authors`, consider the following definition of Logical Models and Native Queries:
+
+<Tabs groupId="user-preference" className="api-tabs">
+<TabItem value="api" label="API">
+
+```http
+POST /v1/metadata HTTP/1.1
+Content-Type: application/json
+X-Hasura-Role: admin
+
+{
+  "type": "bulk_atomic",
+  "args": [
+    {
+      "type": "mssql_track_logical_model",
+      "args": {
+        "description": "",
+        "fields": [
+          {
+            "name": "id",
+            "nullable": false,
+            "type": "integer"
+          },
+          {
+            "name": "title",
+            "nullable": false,
+            "type": "text"
+          },
+          {
+            "name": "author_id",
+            "nullable": false,
+            "type": "integer"
+          }
+        ],
+        "name": "article",
+        "source": "default"
+      }
+    }
+    {
+      "type": "mssql_track_native_query",
+      "args": {
+        "arguments": {},
+        "array_relationships": [],
+        "code": "SELECT * FROM (VALUES (1, 'Logical Models', 1), (2, 'Native Queries', 2), (3, 'Relationships', 3), (4, 'Graph Relationships', 4), (5, 'Permissions', 5)) as t(\"id\", \"title\", \"author_id\")",
+        "object_relationships": [
+          {
+            "name": "author",
+            "using": {
+              "column_mapping": {
+                "author_id": "id"
+              },
+              "insertion_order": null,
+              "remote_table": "authors"
+            }
+          }
+        ],
+        "returns": "article",
+        "root_field_name": "get_articles",
+        "source": "default",
+        "type": "query"
+      }
+    }
+  ]
+}
+```
+
+</TabItem>
+<TabItem value="query" label="Query">
+
+The Native Queries in this example enables queries such as:
+
+```graphql
+query {
+  get_articles {
+    title
+
+    author {
+      name
+    }
+  }
+}
+```
+
+</TabItem>
+</Tabs>

docs/docs/schema/ms-sql-server/table-relationships/create.mdx

@@ -23,9 +23,9 @@ import GraphiQLIDE from '@site/src/components/GraphiQLIDE';
 A relationship from one table/view to another can be created by defining a link between a column of the table/view to a
 column of the other table/view.
 
-Typically, relationships are defined using foreign-key constraints. But in some cases, it might not be possible to use
+Typically, relationships between tables are defined using foreign-key constraints. But in some cases, it might not be
-foreign-key constraints to create the relation. For example, while trying to create a relationship involving a view as
+possible to use foreign-key constraints to create the relationship. For example, while trying to create a relationship
-foreign-keys can't be created on views.
+involving a view or Native Query since foreign-keys cannot be created on them.
 
 ## Using foreign keys {#ms-sql-server-relationships-using-fkey}
 
@@ -588,3 +588,44 @@ X-Hasura-Role: admin
 
 </TabItem>
 </Tabs>
+
+## Tracking relationships between tables and Native Queries
+
+As mentioned in the Introduction section above, a relationship from a table to a Native Query can only be set up manually.
+
+<Tabs groupId="user-preference" className="api-tabs">
+<TabItem value="api" label="API">
+
+Given a table named `articles` and an existing Native Query named `get_author`,
+we can set up a relationship between the two.
+
+```http
+POST /v1/metadata HTTP/1.1
+Content-Type: application/json
+X-Hasura-Role: admin
+
+{
+  "type": "bulk",
+  "args": [
+    {
+      "type": "mssql_create_object_relationship",
+      "args": {
+        "source": "<db_name>",
+        "table": "articles",
+        "name": "author",
+        "using": {
+          "manual_configuration": {
+            "remote_native_query": "get_author",
+            "column_mapping": {
+              "id": "author_id"
+            }
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+</TabItem>
+</Tabs>

docs/docs/schema/ms-sql-server/table-relationships/index.mdx

@@ -9,12 +9,12 @@ keywords:
   - relationship
 ---
 
-# MS SQL Server: Relationships between Tables/Views
+# MS SQL Server: Relationships between Tables/Views/Native Queries
 
 ## Introduction
 
-To make [nested object queries](/queries/ms-sql-server/nested-object-queries.mdx), the tables/views in your database
+To make [nested object queries](/queries/ms-sql-server/nested-object-queries.mdx), the tables/views/Native Queries in
-need to be connected via relationships.
+your database need to be connected via relationships.
 
 Let's say we have the following tables in our database: `authors`, `passport_infos`, `articles` and `tags`.
 

docs/docs/schema/postgres/logical-models.mdx

@@ -285,8 +285,6 @@ X-Hasura-Role: admin
 
 Logical Model fields are allowed to refer to other Logical Models, even recursively, allowing nested data types.
 
-Object or array relationships between Native Queries are an example use of this.
-
 To elaborate on the `article` example above, we can include authors in the data model:
 
 <Tabs groupId="user-preference" className="api-tabs">

docs/docs/schema/postgres/native-queries.mdx

@@ -538,7 +538,7 @@ Unlike tables, relationships for a Native Query have to be given as part of trac
 Native Query is defined by its Logical Model, and the Native Query needs to implement all the fields of the Logical
 Model in order to be tracked successfully.
 
-Currently relationships are only supported between Native Queries residing in the same source.
+Currently relationships are only supported between Native Queries and tables residing in the same source.
 
 As an example, consider the following definition of Logical Models and Native Queries:
 
@@ -572,13 +572,6 @@ X-Hasura-Role: admin
             "name": "author_id",
             "nullable": false,
             "type": "integer"
-          },
-          {
-            "name": "author",
-            "type": {
-              "logical_model": "author",
-              "nullable": false
-            }
           }
         ],
         "name": "article",
@@ -599,15 +592,6 @@ X-Hasura-Role: admin
             "name": "name",
             "nullable": false,
             "type": "text"
-          },
-          {
-            "name": "articles",
-            "type": {
-              "array": {
-                "logical_model": "article"
-              },
-              "nullable": false
-            }
           }
         ],
         "name": "author",
@@ -701,3 +685,94 @@ query {
 
 </TabItem>
 </Tabs>
+
+
+## Relationships with tables
+
+Relationships can be defined between tables and Native Queries residing in the same source.
+
+As an example, given a table `authors`, consider the following definition of Logical Models and Native Queries:
+
+<Tabs groupId="user-preference" className="api-tabs">
+<TabItem value="api" label="API">
+
+```http
+POST /v1/metadata HTTP/1.1
+Content-Type: application/json
+X-Hasura-Role: admin
+
+{
+  "type": "bulk_atomic",
+  "args": [
+    {
+      "type": "pg_track_logical_model",
+      "args": {
+        "description": "",
+        "fields": [
+          {
+            "name": "id",
+            "nullable": false,
+            "type": "integer"
+          },
+          {
+            "name": "title",
+            "nullable": false,
+            "type": "text"
+          },
+          {
+            "name": "author_id",
+            "nullable": false,
+            "type": "integer"
+          }
+        ],
+        "name": "article",
+        "source": "default"
+      }
+    }
+    {
+      "type": "pg_track_native_query",
+      "args": {
+        "arguments": {},
+        "array_relationships": [],
+        "code": "SELECT * FROM (VALUES (1, 'Logical Models', 1), (2, 'Native Queries', 2), (3, 'Relationships', 3), (4, 'Graph Relationships', 4), (5, 'Permissions', 5)) as t(\"id\", \"title\", \"author_id\")",
+        "object_relationships": [
+          {
+            "name": "author",
+            "using": {
+              "column_mapping": {
+                "author_id": "id"
+              },
+              "insertion_order": null,
+              "remote_table": "authors"
+            }
+          }
+        ],
+        "returns": "article",
+        "root_field_name": "get_articles",
+        "source": "default",
+        "type": "query"
+      }
+    }
+  ]
+}
+```
+
+</TabItem>
+<TabItem value="query" label="Query">
+
+The Native Queries in this example enables queries like:
+
+```graphql
+query {
+  get_articles {
+    title
+
+    author {
+      name
+    }
+  }
+}
+```
+
+</TabItem>
+</Tabs>

docs/docs/schema/postgres/table-relationships/create.mdx

@@ -20,12 +20,12 @@ import TabItem from '@theme/TabItem';
 
 ## Introduction
 
-A relationship from one table/view to another can be created by defining a link between a column of the table/view to a
+A relationship from one table/view/Native Query to another can be created by defining a link between a column of the
-column of the other table/view.
+table/view/Native Query to a column of the other table/view/Native Query.
 
-Typically, relationships are defined using foreign-key constraints. But in some cases, it might not be possible to use
+Typically, relationships between tables are defined using foreign-key constraints. But in some cases, it might not be
-foreign-key constraints to create the relation. For example, while trying to create a relationship involving a view as
+possible to use foreign-key constraints to create the relationship. For example, while trying to create a relationship
-foreign-keys can't be created on views.
+involving a view or Native Query since foreign-keys cannot be created on them.
 
 ## Using foreign keys {#pg-relationships-using-fkey}
 
@@ -589,3 +589,44 @@ X-Hasura-Role: admin
 
 </TabItem>
 </Tabs>
+
+## Tracking relationships between tables and Native Queries
+
+As mentioned in the Introduction section above, a relationship from a table to a Native Query can only be set up manually.
+
+<Tabs groupId="user-preference" className="api-tabs">
+<TabItem value="api" label="API">
+
+Given a table named `articles` and an existing Native Query named `get_author`,
+we can set up a relationship between the two.
+
+```http
+POST /v1/metadata HTTP/1.1
+Content-Type: application/json
+X-Hasura-Role: admin
+
+{
+  "type": "bulk",
+  "args": [
+    {
+      "type": "pg_create_object_relationship",
+      "args": {
+        "source": "<db_name>",
+        "table": "articles",
+        "name": "author",
+        "using": {
+          "manual_configuration": {
+            "remote_native_query": "get_author",
+            "column_mapping": {
+              "id": "author_id"
+            }
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+</TabItem>
+</Tabs>

docs/docs/schema/postgres/table-relationships/index.mdx

@@ -9,12 +9,12 @@ keywords:
 slug: index
 ---
 
-# Postgres: Relationships Between Tables/Views
+# Postgres: Relationships Between Tables/Views/Native Queries
 
 ## Introduction
 
-To make [nested object queries](/queries/postgres/nested-object-queries.mdx), the tables/views in your database need to
+To make [nested object queries](/queries/postgres/nested-object-queries.mdx), the tables/views/Native Queries in your
-be connected via relationships.
+database need to be connected via relationships.
 
 Let's say we have the following tables in our database: `authors`, `passport_infos`, `articles` and `tags`.