diff --git a/docs/docs/api-reference/metadata-api/logical-models.mdx b/docs/docs/api-reference/metadata-api/logical-models.mdx index 50888c96875..7b73a51ce34 100644 --- a/docs/docs/api-reference/metadata-api/logical-models.mdx +++ b/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 -marked as nullable or not. +The type of each field can be either a [BigQuery data type](/schema/bigquery/bigquery-types.mdx) +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} diff --git a/docs/docs/api-reference/metadata-api/native-queries.mdx b/docs/docs/api-reference/metadata-api/native-queries.mdx index 147b8fb1857..f77367cb2e9 100644 --- a/docs/docs/api-reference/metadata-api/native-queries.mdx +++ b/docs/docs/api-reference/metadata-api/native-queries.mdx @@ -119,6 +119,8 @@ X-Hasura-Role: admin "description": "" } }, + "array_relationships": , + "object_relationshps": , "code": "", "returns": "" } @@ -185,6 +187,8 @@ X-Hasura-Role: admin "description": "" } }, + "array_relationships": , + "object_relationshps": , "code": "", "returns": "" } diff --git a/docs/docs/schema/bigquery/logical-models/index.mdx b/docs/docs/schema/bigquery/logical-models/index.mdx index d7535d3a30f..fbd3b4d5f23 100644 --- a/docs/docs/schema/bigquery/logical-models/index.mdx +++ b/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": "", - "type": "", + "type": "", "nullable": false | true, "description": "" }, @@ -75,8 +75,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 -marked as nullable or not. +The type of each field can be either a [BigQuery data type](/schema/bigquery/bigquery-types.mdx) +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", - "nullable": true + "type": + { + "scalar": "date", + "nullable": true + }, }, { "name": "is_published", - "type": "boolean" + "type": + { + "scalar": "boolean" + } } ] } @@ -176,6 +192,110 @@ X-Hasura-Role: admin +## 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: + + + + +```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" + } + } + } + ] + } + } + ] +} +``` + + + + ## 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 - -## Relationships - -Currently, Logical Models do not support relationships. They will be supported in a future release. diff --git a/docs/docs/schema/bigquery/logical-models/native-queries.mdx b/docs/docs/schema/bigquery/logical-models/native-queries.mdx index 412dd0a299c..9a54cccc772 100644 --- a/docs/docs/schema/bigquery/logical-models/native-queries.mdx +++ b/docs/docs/schema/bigquery/logical-models/native-queries.mdx @@ -275,6 +275,19 @@ X-Hasura-Role: admin "description": "" } }, + "array_relationships": [ + { + "name": "", + "using": { + "column_mapping": { + "": "" + }, + "remote_native_query: "" + } + } + ], + "object_relationships": , + "description": "", "code": "", "returns": "" } @@ -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): + + + + +```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. + +::: + + + +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 + } + } +} +``` + + diff --git a/docs/docs/schema/ms-sql-server/logical-models/index.mdx b/docs/docs/schema/ms-sql-server/logical-models/index.mdx index 98e6f67e61f..57fa6f9005e 100644 --- a/docs/docs/schema/ms-sql-server/logical-models/index.mdx +++ b/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": "", - "type": "", + "type": "", "nullable": false | true, "description": "" }, @@ -77,7 +77,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). 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", - "nullable": true + "type": + { + "scalar": "date", + "nullable": true + }, }, { "name": "is_published", - "type": "bit" + "type": + { + "scalar": "bit" + } } ] } @@ -177,6 +194,110 @@ X-Hasura-Role: admin +## 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: + + + + +```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" + } + } + } + ] + } + } + ] +} +``` + + + + ## 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 - -## Relationships - -Currently, Logical Models do not support relationships. They will be supported in a future release. diff --git a/docs/docs/schema/ms-sql-server/logical-models/native-queries.mdx b/docs/docs/schema/ms-sql-server/logical-models/native-queries.mdx index 8df4d1b36b6..a3a97715cde 100644 --- a/docs/docs/schema/ms-sql-server/logical-models/native-queries.mdx +++ b/docs/docs/schema/ms-sql-server/logical-models/native-queries.mdx @@ -276,6 +276,19 @@ X-Hasura-Role: admin "description": "" } }, + "array_relationships": [ + { + "name": "", + "using": { + "column_mapping": { + "": "" + }, + "remote_native_query: "" + } + } + ], + "object_relationships": , + "description": "", "code": "", "returns": "" } @@ -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): + + + + +```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. + +::: + + + +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 + } + } +} +``` + + diff --git a/docs/docs/schema/postgres/logical-models/index.mdx b/docs/docs/schema/postgres/logical-models/index.mdx index d1e6ffa769a..a9be64d1af0 100644 --- a/docs/docs/schema/postgres/logical-models/index.mdx +++ b/docs/docs/schema/postgres/logical-models/index.mdx @@ -192,7 +192,7 @@ X-Hasura-Role: admin -## 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.