docs: Port Postgres docs of Native Queries and Logical Models to other supported backends

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/9483
GitOrigin-RevId: e2e52c14cdde2eabb7f23b5d4991fd467609b313

docs/docs/api-reference/metadata-api/logical-models.mdx

@@ -181,7 +181,9 @@ X-Hasura-Role: admin
 }
 ```
 
-The type of each field can be any valid SQL Server data type, and each field can be marked as nullable or not.
+The type of each field can be either a SQL Server data type
+or references to other Logical Models, and each field can be marked as nullable or not, see
+[LogicalModelType](/api-reference/syntax-defs.mdx#logicalmodeltype).
 
 ### Args syntax {#metadata-mssql-track-logical-model-syntax}
 
@@ -308,8 +310,9 @@ X-Hasura-Role: admin
 }
 ```
 
-The type of each field can be any valid [BigQuery data type](/schema/bigquery/bigquery-types.mdx), and each field can be
+The type of each field can be either a [BigQuery data type](/schema/bigquery/bigquery-types.mdx)
-marked as nullable or not.
+or references to other Logical Models, and each field can be marked as nullable or not, see
+[LogicalModelType](/api-reference/syntax-defs.mdx#logicalmodeltype).
 
 ### Args syntax {#metadata-bigquery-track-logical-model-syntax}
 

docs/docs/api-reference/metadata-api/native-queries.mdx

@@ -119,6 +119,8 @@ X-Hasura-Role: admin
         "description": "<optional field description>"
       }
     },
+    "array_relationships": <Native Query relationship>,
+    "object_relationshps": <Native Query relationship>,
     "code": "<SQL query>",
     "returns": "<logical model name>"
   }
@@ -185,6 +187,8 @@ X-Hasura-Role: admin
         "description": "<optional field description>"
       }
     },
+    "array_relationships": <Native Query relationship>,
+    "object_relationshps": <Native Query relationship>,
     "code": "<SQL query>",
     "returns": "<logical model name>"
   }

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

@@ -22,7 +22,7 @@ import ProductBadge from '@site/src/components/ProductBadge';
 
 :::tip Supported from
 
-Native queries are supported from `v2.26.0`.
+Logical Models are supported from `v2.26.0`.
 
 :::
 
@@ -62,7 +62,7 @@ X-Hasura-Role: admin
     "fields": [
       {
         "name": "<field name>",
-        "type": "<BigQuery field type>",
+        "type": "<BigQuery Logical Model type>",
         "nullable": false | true,
         "description": "<optional field description>"
       },
@@ -75,8 +75,9 @@ X-Hasura-Role: admin
 </TabItem>
 </Tabs>
 
-The type of each field can be any valid [BigQuery data type](/schema/bigquery/bigquery-types.mdx), and each field can be
+The type of each field can be either a [BigQuery data type](/schema/bigquery/bigquery-types.mdx)
-marked as nullable or not.
+or references to other Logical Models, and each field can be marked as nullable or not, see
+[LogicalModelType](/api-reference/syntax-defs.mdx#logicalmodeltype).
 
 For example, we could track a representation of an article as follows:
 
@@ -96,24 +97,39 @@ X-Hasura-Role: admin
     "fields": [
       {
         "name": "id",
-        "type": "integer"
+        "type":
+          {
+            "scalar": "integer"
+          }
       },
       {
         "name": "title",
-        "type": "text"
+        "type":
+          {
+            "scalar": "text"
+          }
       },
       {
         "name": "contents",
-        "type": "text"
+        "type":
+          {
+            "scalar": "text"
+          }
       },
       {
         "name": "published_date",
-        "type": "published_date",
+        "type":
+          {
+            "scalar": "date",
             "nullable": true
           },
+      },
       {
         "name": "is_published",
-        "type": "boolean"
+        "type":
+          {
+            "scalar": "boolean"
+          }
       }
     ]
   }
@@ -176,6 +192,110 @@ X-Hasura-Role: admin
 </TabItem>
 </Tabs>
 
+## Referencing other Logical Models {#referencing-other-logical-models}
+
+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">
+<TabItem value="api" label="API">
+
+```http
+POST /v1/metadata HTTP/1.1
+Content-Type: application/json
+X-Hasura-Role: admin
+
+{
+  "type": "bulk",
+  "args":
+  [
+    {
+      "type": "bigquery_track_logical_model",
+      "args": {
+        "source": "default",
+        "name": "article",
+        "fields": [
+          {
+            "name": "id",
+            "type":
+              {
+                "scalar": "integer"
+              }
+          },
+          {
+            "name": "title",
+            "type":
+              {
+                "scalar": "text"
+              }
+          },
+          {
+            "name": "contents",
+            "type":
+              {
+                "scalar": "text"
+              }
+          },
+          {
+            "name": "author_id",
+            "type":
+              {
+                "scalar": "integer"
+              }
+          },
+          {
+            "name": "author",
+            "type":
+              {
+                "logical_model": "author",
+              },
+          }
+        ]
+      }
+    },
+    {
+      "type": "bigquery_track_logical_model",
+      "args": {
+        "source": "default",
+        "name": "author",
+        "fields": [
+          {
+            "name": "id",
+            "type":
+              {
+                "scalar": "integer"
+              }
+          },
+          {
+            "name": "name",
+            "type":
+              {
+                "scalar": "text"
+              }
+          },
+          {
+            "name": "articles",
+            "type":
+              {
+                "array":
+                  {
+                    "logical_model": "article"
+                  }
+              }
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+</TabItem>
+</Tabs>
+
 ## Permissions
 
 By default, a model has no permissions, and only the admin account will be able to use it. You can enable the model by
@@ -278,7 +398,3 @@ X-Hasura-Role: admin
 
 </TabItem>
 </Tabs>
-
-## Relationships
-
-Currently, Logical Models do not support relationships. They will be supported in a future release.

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

@@ -275,6 +275,19 @@ X-Hasura-Role: admin
         "description": "<optional field description>"
       }
     },
+    "array_relationships": [
+      {
+        "name": "<relationship name>",
+        "using": {
+          "column_mapping": {
+            "<local column>": "<remote column>"
+          },
+          "remote_native_query: "<remote native query name>"
+        }
+      }
+    ],
+    "object_relationships": <same as array_relationships>,
+    "description": "<text>",
     "code": "<SQL query>",
     "returns": "<logical model name>"
   }
@@ -342,3 +355,129 @@ A future release will allow mutations to be specified using native queries.
 Native queries will inherit the permissions of the Logical Model that they return. See the
 [documentation on Logical Models](/schema/bigquery/logical-models/index.mdx) for an explanation of how to add
 permissions.
+
+## Relationships
+
+Relationships are supported between Native Queries.
+This is how Native Queries may implement object and array fields of their referenced Logical Model.
+
+Unlike tables, relationships for a Native Query have to be given as part of
+tracking the Native Query: The schema of a 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.
+
+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/index.mdx#referencing-other-logical-models):
+
+<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":
+  [
+    { "args": {
+        "arguments": {
+          "length": {
+            "nullable": false,
+            "type": "integer"
+          }
+        },
+        "array_relationships": [],
+        "code": "
+          SELECT
+            id,
+            title,
+            (substring(content, 1, {{length}}) ||
+              (CASE WHEN length(content) < {{length}}
+               THEN '' ELSE '...' END))
+               AS contents,
+            date
+          FROM article",
+        "object_relationships": [
+          {
+            "name": "author",
+            "using": {
+              "column_mapping": {
+                "author_id": "id"
+              },
+              "remote_native_query": "get_authors"
+            }
+          }
+        ],
+        "returns": "article",
+        "root_field_name": "get_articles",
+        "source": "bigquery",
+        "type": "query"
+      },
+      "type": "bigquery_track_native_query"
+    },
+    ,{ "args": {
+        "arguments": {},
+        "array_relationships": [
+          {
+            "name": "articles",
+            "using": {
+              "column_mapping": {
+                "id": "author_id"
+              },
+              "remote_native_query": "get_articles"
+            }
+          }
+         ],
+        "code": "SELECT * FROM authors",
+        "object_relationships": [],
+        "returns": "author",
+        "root_field_name": "get_authors",
+        "source": "bigquery",
+        "type": "query"
+      },
+      "type": "bigquery_track_native_query"
+    }
+  ]
+}
+```
+
+:::info Wrap calls in `bulk_atomic`
+
+Similar to Logical Models, tracking the Native Queries one-by-one would fail,
+since `get_articles` refers to `get_authors`, which is not yet defined.
+
+Tracking the Native Queries in one atomic operation postpones coherency checks
+until all models are tracked, which allows for mutual references.
+
+:::
+
+</TabItem>
+<TabItem value="query" label="Query">
+The Native Queries in this example enable queries like:
+
+```graphql
+query {
+  get_authors
+  {
+    name
+
+    short_excerpt: articles(args: {length: 10})
+    {
+      title
+      contents
+    }
+
+    long_excerpt: articles(args: {length: 100})
+    {
+      title
+      contents
+    }
+  }
+}
+```
+</TabItem>
+</Tabs>

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

@@ -23,7 +23,7 @@ import ProductBadge from '@site/src/components/ProductBadge';
 
 :::tip Supported from
 
-Native queries are supported from `v2.26.0`.
+Logical Models are supported from `v2.26.0`.
 
 :::
 
@@ -64,7 +64,7 @@ X-Hasura-Role: admin
     "fields": [
       {
         "name": "<field name>",
-        "type": "<SQL Server field type>",
+        "type": "<SQL Server Logical Model type>",
         "nullable": false | true,
         "description": "<optional field description>"
       },
@@ -77,7 +77,9 @@ X-Hasura-Role: admin
 </TabItem>
 </Tabs>
 
-The type of each field can be any valid SQL Server data type, and each field can be marked as nullable or not.
+The type of each field can be either a SQL Server data type
+or references to other Logical Models, and each field can be marked as nullable or not, see
+[LogicalModelType](/api-reference/syntax-defs.mdx#logicalmodeltype).
 
 For example, we could track a representation of an article as follows:
 
@@ -97,24 +99,39 @@ X-Hasura-Role: admin
     "fields": [
       {
         "name": "id",
-        "type": "int"
+        "type":
+          {
+            "scalar": "int"
+          }
       },
       {
         "name": "title",
-        "type": "text"
+        "type":
+          {
+            "scalar": "text"
+          }
       },
       {
         "name": "contents",
-        "type": "text"
+        "type":
+          {
+            "scalar": "text"
+          }
       },
       {
         "name": "published_date",
-        "type": "published_date",
+        "type":
+          {
+            "scalar": "date",
             "nullable": true
           },
+      },
       {
         "name": "is_published",
-        "type": "bit"
+        "type":
+          {
+            "scalar": "bit"
+          }
       }
     ]
   }
@@ -177,6 +194,110 @@ X-Hasura-Role: admin
 </TabItem>
 </Tabs>
 
+## Referencing other Logical Models {#referencing-other-logical-models}
+
+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">
+<TabItem value="api" label="API">
+
+```http
+POST /v1/metadata HTTP/1.1
+Content-Type: application/json
+X-Hasura-Role: admin
+
+{
+  "type": "bulk",
+  "args":
+  [
+    {
+      "type": "mssql_track_logical_model",
+      "args": {
+        "source": "default",
+        "name": "article",
+        "fields": [
+          {
+            "name": "id",
+            "type":
+              {
+                "scalar": "integer"
+              }
+          },
+          {
+            "name": "title",
+            "type":
+              {
+                "scalar": "text"
+              }
+          },
+          {
+            "name": "contents",
+            "type":
+              {
+                "scalar": "text"
+              }
+          },
+          {
+            "name": "author_id",
+            "type":
+              {
+                "scalar": "integer"
+              }
+          },
+          {
+            "name": "author",
+            "type":
+              {
+                "logical_model": "author",
+              },
+          }
+        ]
+      }
+    },
+    {
+      "type": "mssql_track_logical_model",
+      "args": {
+        "source": "default",
+        "name": "author",
+        "fields": [
+          {
+            "name": "id",
+            "type":
+              {
+                "scalar": "integer"
+              }
+          },
+          {
+            "name": "name",
+            "type":
+              {
+                "scalar": "text"
+              }
+          },
+          {
+            "name": "articles",
+            "type":
+              {
+                "array":
+                  {
+                    "logical_model": "article"
+                  }
+              }
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+</TabItem>
+</Tabs>
+
 ## Permissions
 
 By default, a model has no permissions, and only the admin account will be able to use it. You can enable the model by
@@ -279,7 +400,3 @@ X-Hasura-Role: admin
 
 </TabItem>
 </Tabs>
-
-## Relationships
-
-Currently, Logical Models do not support relationships. They will be supported in a future release.

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

@@ -276,6 +276,19 @@ X-Hasura-Role: admin
         "description": "<optional field description>"
       }
     },
+    "array_relationships": [
+      {
+        "name": "<relationship name>",
+        "using": {
+          "column_mapping": {
+            "<local column>": "<remote column>"
+          },
+          "remote_native_query: "<remote native query name>"
+        }
+      }
+    ],
+    "object_relationships": <same as array_relationships>,
+    "description": "<text>",
     "code": "<SQL query>",
     "returns": "<logical model name>"
   }
@@ -344,3 +357,129 @@ A future release will allow mutations to be specified using native queries.
 Native queries will inherit the permissions of the Logical Model that they return. See the
 [documentation on Logical Models](/schema/ms-sql-server/logical-models/index.mdx) for an explanation of how to add
 permissions.
+
+## Relationships
+
+Relationships are supported between Native Queries.
+This is how Native Queries may implement object and array fields of their referenced Logical Model.
+
+Unlike tables, relationships for a Native Query have to be given as part of
+tracking the Native Query: The schema of a 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.
+
+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/index.mdx#referencing-other-logical-models):
+
+<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":
+  [
+    { "args": {
+        "arguments": {
+          "length": {
+            "nullable": false,
+            "type": "integer"
+          }
+        },
+        "array_relationships": [],
+        "code": "
+          SELECT
+            id,
+            title,
+            (substring(content, 1, {{length}}) ||
+              (CASE WHEN length(content) < {{length}}
+               THEN '' ELSE '...' END))
+               AS contents,
+            date
+          FROM article",
+        "object_relationships": [
+          {
+            "name": "author",
+            "using": {
+              "column_mapping": {
+                "author_id": "id"
+              },
+              "remote_native_query": "get_authors"
+            }
+          }
+        ],
+        "returns": "article",
+        "root_field_name": "get_articles",
+        "source": "mssql",
+        "type": "query"
+      },
+      "type": "mssql_track_native_query"
+    },
+    ,{ "args": {
+        "arguments": {},
+        "array_relationships": [
+          {
+            "name": "articles",
+            "using": {
+              "column_mapping": {
+                "id": "author_id"
+              },
+              "remote_native_query": "get_articles"
+            }
+          }
+         ],
+        "code": "SELECT * FROM authors",
+        "object_relationships": [],
+        "returns": "author",
+        "root_field_name": "get_authors",
+        "source": "mssql",
+        "type": "query"
+      },
+      "type": "mssql_track_native_query"
+    }
+  ]
+}
+```
+
+:::info Wrap calls in `bulk_atomic`
+
+Similar to Logical Models, tracking the Native Queries one-by-one would fail,
+since `get_articles` refers to `get_authors`, which is not yet defined.
+
+Tracking the Native Queries in one atomic operation postpones coherency checks
+until all models are tracked, which allows for mutual references.
+
+:::
+
+</TabItem>
+<TabItem value="query" label="Query">
+The Native Queries in this example enable queries like:
+
+```graphql
+query {
+  get_authors
+  {
+    name
+
+    short_excerpt: articles(args: {length: 10})
+    {
+      title
+      contents
+    }
+
+    long_excerpt: articles(args: {length: 100})
+    {
+      title
+      contents
+    }
+  }
+}
+```
+</TabItem>
+</Tabs>

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

@@ -192,7 +192,7 @@ X-Hasura-Role: admin
 </TabItem>
 </Tabs>
 
-## Referencing other logical models {#referencing-other-logical-models}
+## Referencing other Logical Models {#referencing-other-logical-models}
 
 Logical Model fields are allowed to refer to other Logical Models, even recursively, allowing nested data types.