hasura/graphql-engine
1
0
Fork 0
mirror of https://github.com/hasura/graphql-engine.git synced 2024-12-14 17:02:49 +03:00
Code Issues Projects Releases Wiki Activity

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

Browse Source 
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/9483
GitOrigin-RevId: e2e52c14cdde2eabb7f23b5d4991fd467609b313
This commit is contained in:
Philip Lykke Carlsen 2023-06-09 15:56:57 +02:00 committed by hasura-bot
parent 89ca064db5
commit 42916ad6c2
7 changed files with 549 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
docs/docs/api-reference/metadata-api/logical-models.mdx
View File

@ -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}

4
docs/docs/api-reference/metadata-api/native-queries.mdx
View File

@ -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>"
}

142
docs/docs/schema/bigquery/logical-models/index.mdx
View File

@ -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
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",
"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.

139
docs/docs/schema/bigquery/logical-models/native-queries.mdx
View File

@ -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>

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

@ -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.

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

@ -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>

2
docs/docs/schema/postgres/logical-models/index.mdx
View File

@ -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.