hasura/graphql-engine
1
0
Fork 0
mirror of https://github.com/hasura/graphql-engine.git synced 2024-09-11 10:46:25 +03:00
Code Issues Projects Releases Wiki Activity

docs: improve logical model and native queries docs

Browse Source 
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/9592
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
GitOrigin-RevId: 5825d652bf765c6e8845856971e766ca43f86433
This commit is contained in:
Rob Dominguez 2023-07-24 09:59:38 -05:00 committed by hasura-bot
parent f2454b9854
commit 8b0a4a117b
13 changed files with 292 additions and 292 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -39,11 +39,10 @@ Logical Models themselves, read on.
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">
<Thumbnail
src="/img/native-queries/create-logical-model-excerpt-example.png"
alt="Create Logical Model"
width="800px"
/>
You can create a Logical Model from the "Data" tab of the Console, by clicking on `Native Queries` in the sidebar, then
`Add Logical Model`:
<Thumbnail src="/img/native-queries/logical-model-add.png" alt="Create Logical Model" width="800px" />
</TabItem>
@ -95,15 +94,16 @@ X-Hasura-Role: admin
</TabItem>
</Tabs>
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
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:
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">
For example, we could track a representation of an article with excerpts as follows, by defining the fields we want to
be able to return:
<Thumbnail
src="/img/native-queries/create-logical-model-excerpt-example.png"
alt="Create Logical Model"
@ -117,24 +117,24 @@ For example, we could track a representation of an article as follows:
Add the following to the `default` database definition in the `metadata > databases.yaml` file:
```yaml
logical_models:
- name: article
fields:
id:
type: integer
nullable: false
title:
type: text
nullable: false
contents:
type: text
nullable: false
published_date:
type: date
nullable: true
is_published:
type: boolean
nullable: false
logical_models:
- name: article
fields:
id:
type: integer
nullable: false
title:
type: text
nullable: false
contents:
type: text
nullable: false
published_date:
type: date
nullable: true
is_published:
type: boolean
nullable: false
```
</TabItem>
@ -201,11 +201,9 @@ X-Hasura-Role: admin
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">
<Thumbnail
src="/img/native-queries/delete-logical-model.png"
alt="Delete Logical Model"
width="800px"
/>
To untrack a Logical Model, click `Remove` next to the Logical Model:
<Thumbnail src="/img/native-queries/delete-logical-model.png" alt="Delete Logical Model" width="800px" />
</TabItem>
@ -243,7 +241,7 @@ will fail. You must remove the Native Query first.
:::
To untrack the above "article" Logical Model, we would run the following:
To untrack the above `article` Logical Model, we would run the following:
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">
@ -286,7 +284,7 @@ Logical Model fields are allowed to refer to other Logical Models, even recursiv
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:
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">
@ -471,7 +469,7 @@ X-Hasura-Role: admin
</TabItem>
</Tabs>
For example, to allow access to the "article" Logical Model for the "reader" role, but only for published articles, we
For example, to allow access to the `article` Logical Model for the `reader` role, but only for published articles, we
could use the following permission to limit the accessible rows to those where `is_published` is `true`, and then hide
that column from the list (by specifying all other columns).
@ -487,22 +485,21 @@ that column from the list (by specifying all other columns).
Add the required permissions to the relevant logical model in `metadata > databases.yaml`:
```yaml
logical_models:
- name: "<name>"
fields:
...
select_permissions:
- role: reader
permission:
columns:
- id
- title
- contents
- date
filter:
is_published:
_eq: true
- ...
logical_models:
- name: '<name>'
fields: ...
select_permissions:
- role: reader
permission:
columns:
- id
- title
- contents
- date
filter:
is_published:
_eq: true
- ...
```
</TabItem>

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

@ -93,7 +93,7 @@ Click on the `Logical Models` tab, and on the `Add Logical Model` button.
<Thumbnail src="/img/native-queries/logical-model-add.png" alt="Create Logical Model" width="800px" />
Once the modal is open, fill in the form.
Once the modal is open, fill in the form. Each added field will be returned as a field in the GraphQL schema.
<Thumbnail
src="/img/native-queries/create-logical-model-excerpt-example.png"
@ -108,17 +108,17 @@ Once the modal is open, fill in the form.
Add the following to the `default` database definition in the `metadata > databases.yaml` file:
```yaml
logical_models:
- name: article_excerpt
fields:
id:
type: integer
title:
type: text
date:
type: date
excerpt:
type: text
logical_models:
- name: article_excerpt
fields:
id:
type: integer
title:
type: text
date:
type: date
excerpt:
type: text
```
</TabItem>
@ -200,13 +200,15 @@ FROM article
Add the following to the `default` database definition in the `metadata > databases.yaml` file:
```yaml
native_queries:
- root_field_name: article_with_excerpt
arguments:
max_length:
type: integer
code: SELECT id, title, (substring(content, 1, {{max_length}}) || (CASE WHEN length(content) < {{max_length}} THEN '' else '...' END)) AS excerpt, date FROM article
returns: article_excerpt
native_queries:
- root_field_name: article_with_excerpt
arguments:
max_length:
type: integer
code:
SELECT id, title, (substring(content, 1, {{max_length}}) || (CASE WHEN length(content) < {{max_length}} THEN ''
else '...' END)) AS excerpt, date FROM article
returns: article_excerpt
```
</TabItem>
@ -289,8 +291,8 @@ In order to represent the structure of the data returned by the query, we first
:::info Permissions and Logical Models
Note that this Logical Model has no attached permissions and therefore will only be available to the admin role. See
the [Logical Model documentation](/schema/bigquery/logical-models/index.mdx) for information on attaching permissions.
Note that this Logical Model has no attached permissions and therefore will only be available to the admin role. See the
[Logical Model documentation](/schema/bigquery/logical-models/index.mdx) for information on attaching permissions.
:::
@ -464,8 +466,8 @@ You can use any SQL that you could potentially use in a parameterized query, wit
The query can take arguments, which are specified in the metadata. These arguments can be used in the SQL using the
syntax `{{argument_name}}`. This syntax resembles popular string templating languages such as Mustache, but does not use
string interpolation. Instead, it works in exactly the same way as parameterized queries in the database, and so arguments
do not need escaping or quoting in the SQL itself. They will be treated as variables of the correct type.
string interpolation. Instead, it works in exactly the same way as parameterized queries in the database, and so
arguments do not need escaping or quoting in the SQL itself. They will be treated as variables of the correct type.
This does mean that arguments cannot be used for elements of the SQL that deal with structure. For example, you cannot
use an argument to specify the name of the table in a `FROM` clause.
@ -522,17 +524,17 @@ permissions.
## Relationships
Relationships are supported between Native Queries.
This is how Native Queries may implement object and array fields of their referenced Logical Model.
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.
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 definition of Logical Models and Native Queries:
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">
@ -660,11 +662,11 @@ X-Hasura-Role: admin
:::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.
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.
Tracking the Native Queries in one atomic operation postpones coherency checks until all models are tracked, which
allows for mutual references.
:::
@ -674,23 +676,21 @@ The Native Queries in this example enable queries like:
```graphql
query {
get_authors
{
get_authors {
name
short_excerpt: articles(args: {length: 10})
{
short_excerpt: articles(args: { length: 10 }) {
title
contents
}
long_excerpt: articles(args: {length: 100})
{
long_excerpt: articles(args: { length: 100 }) {
title
contents
}
}
}
```
</TabItem>
</Tabs>

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

@ -96,9 +96,8 @@ X-Hasura-Role: admin
</TabItem>
</Tabs>
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).
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:
@ -118,24 +117,24 @@ For example, we could track a representation of an article as follows:
Add the following to the `default` database definition in the `metadata > databases.yaml` file:
```yaml
logical_models:
- name: article
fields:
id:
type: integer
nullable: false
title:
type: text
nullable: false
contents:
type: text
nullable: false
published_date:
type: date
nullable: true
is_published:
type: bit
nullable: false
logical_models:
- name: article
fields:
id:
type: integer
nullable: false
title:
type: text
nullable: false
contents:
type: text
nullable: false
published_date:
type: date
nullable: true
is_published:
type: bit
nullable: false
```
</TabItem>
@ -202,11 +201,7 @@ X-Hasura-Role: admin
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">
<Thumbnail
src="/img/native-queries/delete-logical-model.png"
alt="Delete Logical Model"
width="800px"
/>
<Thumbnail src="/img/native-queries/delete-logical-model.png" alt="Delete Logical Model" width="800px" />
</TabItem>
@ -244,16 +239,12 @@ will fail. You must remove the Native Query first.
:::
To untrack the above "article" Logical Model, we would run the following:
To untrack the above `article` Logical Model, we would run the following:
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">
<Thumbnail
src="/img/native-queries/delete-logical-model.png"
alt="Delete Logical Model"
width="800px"
/>
<Thumbnail src="/img/native-queries/delete-logical-model.png" alt="Delete Logical Model" width="800px" />
</TabItem>
@ -288,7 +279,7 @@ Logical Model fields are allowed to refer to other Logical Models, even recursiv
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:
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">
@ -473,7 +464,7 @@ X-Hasura-Role: admin
</TabItem>
</Tabs>
For example, to allow access to the "article" Logical Model for the "reader" role, but only for published articles, we
For example, to allow access to the `article` Logical Model for the `reader` role, but only for published articles, we
could use the following permission to limit the accessible rows to those where `is_published` is `true`, and then hide
that column from the list (by specifying all other columns).
@ -489,22 +480,21 @@ that column from the list (by specifying all other columns).
Add the required permissions to the relevant logical model in `metadata > databases.yaml`:
```yaml
logical_models:
- name: "<name>"
fields:
...
select_permissions:
- role: reader
permission:
columns:
- id
- title
- contents
- date
filter:
is_published:
_eq: true
- ...
logical_models:
- name: '<name>'
fields: ...
select_permissions:
- role: reader
permission:
columns:
- id
- title
- contents
- date
filter:
is_published:
_eq: true
- ...
```
</TabItem>

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

@ -93,7 +93,7 @@ Click on the `Logical Models` tab, and on the `Add Logical Model` button.
<Thumbnail src="/img/native-queries/logical-model-add.png" alt="Create Logical Model" width="800px" />
Once the modal is open, fill in the form.
Once the modal is open, fill in the form. Each added field will be returned as a field in the GraphQL schema.
<Thumbnail
src="/img/native-queries/create-logical-model-excerpt-example.png"
@ -108,17 +108,17 @@ Once the modal is open, fill in the form.
Add the following to the `default` database definition in the `metadata > databases.yaml` file:
```yaml
logical_models:
- name: article_excerpt
fields:
id:
type: integer
title:
type: text
date:
type: date
excerpt:
type: text
logical_models:
- name: article_excerpt
fields:
id:
type: integer
title:
type: text
date:
type: date
excerpt:
type: text
```
</TabItem>
@ -173,21 +173,21 @@ Click on the `Native Queries` tab and `Create Native Query` button.
<Thumbnail src="/img/native-queries/native-query-create.png" alt="Create Native Query" width="1146px" />
Fill in the form with the data required:
Then, fill in the form with the data required:
Fill in the form with the data required:
- Native Query name `article_with_excerpt`
- The database to be used
- The input parameter `max_length`
- The Native Query statement
| Field | Value |
| -------------------------- | ------------------------------- |
| Native Query name | `article_with_excerpt` |
| Database | The database to be used |
| Input parameter | `max_length`, of type `integer` |
| The Native Query statement | Value below 👇 |
```sql
SELECT id, title, (substring(content, 1, {{max_length}}) || (CASE WHEN length(content) < {{max_length}} THEN '' else '...' END)) AS excerpt, date
FROM article
```
- The query return type, the Logical Model previously created `article_excerpt`
Finally, at the end, add the Query Return Type as the `article_excerpt` Logical Model we created and click `Save`:
<Thumbnail
src="/img/native-queries/create-native-query-excerpt-example.png"
@ -202,13 +202,15 @@ FROM article
Add the following to the `default` database definition in the `metadata > databases.yaml` file:
```yaml
native_queries:
- root_field_name: article_with_excerpt
arguments:
max_length:
type: integer
code: SELECT id, title, (substring(content, 1, {{max_length}}) || (CASE WHEN length(content) < {{max_length}} THEN '' else '...' END)) AS excerpt, date FROM article
returns: article_excerpt
native_queries:
- root_field_name: article_with_excerpt
arguments:
max_length:
type: integer
code:
SELECT id, title, (substring(content, 1, {{max_length}}) || (CASE WHEN length(content) < {{max_length}} THEN ''
else '...' END)) AS excerpt, date FROM article
returns: article_excerpt
```
</TabItem>
@ -291,9 +293,8 @@ In order to represent the structure of the data returned by the query, we first
:::info Permissions and Logical Models
Note that this Logical Model has no attached permissions and therefore will only be available to the admin role. See
the [Logical Model documentation](/schema/ms-sql-server/logical-models/index.mdx) for information on attaching
permissions.
Note that this Logical Model has no attached permissions and therefore will only be available to the admin role. See the
[Logical Model documentation](/schema/ms-sql-server/logical-models/index.mdx) for information on attaching permissions.
:::
@ -310,9 +311,13 @@ Click on the `Logical Models` tab, and on the `Add Logical Model` button.
Once the modal is open, fill in the forms with:
- The database to use as source
- The Logical Model name
- The optional input fields
| Field | Value |
| ------------------ | ----------------------------- |
| Source | The database to be used |
| Logical Model Name | The name of the Logical Model |
Finally, add any optional fields that you would like to be included in the Logical Model and click
`Create Logical Model`.
<Thumbnail src="/img/native-queries/logical-model-modal.png" alt="Create Logical Model" width="800px" />
@ -375,14 +380,17 @@ Click on the `Native Queries` tab and `Create Native Query` button.
<Thumbnail src="/img/native-queries/native-query-create.png" alt="Create Native Query" width="1146px" />
Fill in the form with the data required:
Then, fill in the form with the data required:
- Native Query name
- An optional comment
- The database to be used
- Optional input parameters to be send to the Native Query
- The Native Query statement
- The query return type (the Logical Model previously created)
| Field | Value |
| -------------------------- | ------------------------------- |
| Native Query name | `article_with_excerpt` |
| Database | The database to be used |
| Input parameter | `max_length`, of type `integer` |
| The Native Query statement | Your SQL statement. |
| Query Return Type | The Logical Model created above |
Finally, click `Save`.
<Thumbnail src="/img/native-queries/create-native-query.png" alt="Create Native Query Form" width="1146px" />
@ -467,8 +475,8 @@ You can use any SQL that you could potentially use in a parameterized query, wit
The query can take arguments, which are specified in the metadata. These arguments can be used in the SQL using the
syntax `{{argument_name}}`. This syntax resembles popular string templating languages such as Mustache, but does not use
string interpolation. Instead, it works in exactly the same way as parameterized queries in the database, and so arguments
do not need escaping or quoting in the SQL itself. They will be treated as variables of the correct type.
string interpolation. Instead, it works in exactly the same way as parameterized queries in the database, and so
arguments do not need escaping or quoting in the SQL itself. They will be treated as variables of the correct type.
This does mean that arguments cannot be used for elements of the SQL that deal with structure. For example, you cannot
use an argument to specify the name of the table in a `FROM` clause.
@ -526,17 +534,17 @@ permissions.
## Relationships
Relationships are supported between Native Queries.
This is how Native Queries may implement object and array fields of their referenced Logical Model.
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.
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 definition of Logical Models and Native Queries:
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">
@ -664,11 +672,11 @@ X-Hasura-Role: admin
:::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.
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.
Tracking the Native Queries in one atomic operation postpones coherency checks until all models are tracked, which
allows for mutual references.
:::
@ -678,23 +686,21 @@ The Native Queries in this example enable queries like:
```graphql
query {
get_authors
{
get_authors {
name
short_excerpt: articles(args: {length: 10})
{
short_excerpt: articles(args: { length: 10 }) {
title
contents
}
long_excerpt: articles(args: {length: 100})
{
long_excerpt: articles(args: { length: 100 }) {
title
contents
}
}
}
```
</TabItem>
</Tabs>

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

@ -41,11 +41,10 @@ Logical Models themselves, read on.
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">
<Thumbnail
src="/img/native-queries/create-logical-model-excerpt-example.png"
alt="Create Logical Model"
width="800px"
/>
You can create a Logical Model from the "Data" tab of the Console, by clicking on `Native Queries` in the sidebar, then
`Add Logical Model`:
<Thumbnail src="/img/native-queries/logical-model-add.png" alt="Create Logical Model" width="800px" />
</TabItem>
@ -101,11 +100,12 @@ The type of each field can be either a [PostgreSQL data type](/schema/postgres/p
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:
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">
For example, we could track a representation of an article with excerpts as follows, by defining the fields we want to
be able to return:
<Thumbnail
src="/img/native-queries/create-logical-model-excerpt-example.png"
alt="Create Logical Model"
@ -119,30 +119,33 @@ For example, we could track a representation of an article as follows:
Add the following to the `default` database definition in the `metadata > databases.yaml` file:
```yaml
logical_models:
- name: article
fields:
id:
type: integer
nullable: false
title:
type: text
nullable: false
contents:
type: text
nullable: false
published_date:
type: date
nullable: true
is_published:
type: boolean
nullable: false
logical_models:
- name: article
fields:
id:
type: integer
nullable: false
title:
type: text
nullable: false
contents:
type: text
nullable: false
published_date:
type: date
nullable: true
is_published:
type: boolean
nullable: false
```
</TabItem>
<TabItem value="api" label="API">
For example, we could track a representation of an article with excerpts as follows, by defining the fields we want to
be able to return:
```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
@ -203,11 +206,9 @@ X-Hasura-Role: admin
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">
<Thumbnail
src="/img/native-queries/delete-logical-model.png"
alt="Delete Logical Model"
width="800px"
/>
To untrack a Logical Model, click `Remove` next to the Logical Model:
<Thumbnail src="/img/native-queries/delete-logical-model.png" alt="Delete Logical Model" width="800px" />
</TabItem>
@ -245,16 +246,12 @@ will fail. You must remove the Native Query first.
:::
To untrack the above "article" Logical Model, we would run the following:
To untrack the above `article` Logical Model, we would run the following:
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">
<Thumbnail
src="/img/native-queries/delete-logical-model.png"
alt="Delete Logical Model"
width="800px"
/>
<Thumbnail src="/img/native-queries/delete-logical-model.png" alt="Delete Logical Model" width="800px" />
</TabItem>
@ -289,7 +286,7 @@ Logical Model fields are allowed to refer to other Logical Models, even recursiv
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:
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">
@ -474,7 +471,7 @@ X-Hasura-Role: admin
</TabItem>
</Tabs>
For example, to allow access to the "article" Logical Model for the "reader" role, but only for published articles, we
For example, to allow access to the `article` Logical Model for the `reader` role, but only for published articles, we
could use the following permission to limit the accessible rows to those where `is_published` is `true`, and then hide
that column from the list (by specifying all other columns).
@ -490,22 +487,21 @@ that column from the list (by specifying all other columns).
Add the required permissions to the relevant logical model in `metadata > databases.yaml`:
```yaml
logical_models:
- name: "<name>"
fields:
...
select_permissions:
- role: reader
permission:
columns:
- id
- title
- contents
- date
filter:
is_published:
_eq: true
- ...
logical_models:
- name: '<name>'
fields: ...
select_permissions:
- role: reader
permission:
columns:
- id
- title
- contents
- date
filter:
is_published:
_eq: true
- ...
```
</TabItem>

87
docs/docs/schema/postgres/logical-models/native-queries.mdx
View File

@ -89,7 +89,7 @@ Click on the `Logical Models` tab, and on the `Add Logical Model` button.
<Thumbnail src="/img/native-queries/logical-model-add.png" alt="Create Logical Model" width="800px" />
Once the modal is open, fill in the form.
Once the modal is open, fill in the form. Each added field will be returned as a field in the GraphQL schema.
<Thumbnail
src="/img/native-queries/create-logical-model-excerpt-example.png"
@ -104,17 +104,17 @@ Once the modal is open, fill in the form.
Add the following to the `default` database definition in the `metadata > databases.yaml` file:
```yaml
logical_models:
- name: article_excerpt
fields:
id:
type: integer
title:
type: text
date:
type: date
excerpt:
type: text
logical_models:
- name: article_excerpt
fields:
id:
type: integer
title:
type: text
date:
type: date
excerpt:
type: text
```
</TabItem>
@ -165,23 +165,25 @@ We use `{{max_length}}` to refer to the argument. We need it twice, so we simply
<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">
Click on the `Native Queries` tab and `Create Native Query` button.
To start, click on the `Native Queries` tab and `Create Native Query` button:
<Thumbnail src="/img/native-queries/native-query-create.png" alt="Create Native Query" width="1146px" />
Fill in the form with the data required:
Then, fill in the form with the data required:
- Native Query name `article_with_excerpt`
- The database to be used
- The input parameter `max_length`
- The Native Query statement
| Field | Value |
| -------------------------- | ------------------------------- |
| Native Query name | `article_with_excerpt` |
| Database | The database to be used |
| Input parameter | `max_length`, of type `integer` |
| The Native Query statement | Value below 👇 |
```sql
SELECT id, title, (substring(content, 1, {{max_length}}) || (CASE WHEN length(content) < {{max_length}} THEN '' else '...' END)) AS excerpt, date
FROM article
```
- The query return type, the Logical Model previously created `article_excerpt`
Finally, at the end, add the Query Return Type as the `article_excerpt` Logical Model we created and click `Save`:
<Thumbnail
src="/img/native-queries/create-native-query-excerpt-example.png"
@ -196,13 +198,15 @@ FROM article
Add the following to the `default` database definition in the `metadata > databases.yaml` file:
```yaml
native_queries:
- root_field_name: article_with_excerpt
arguments:
max_length:
type: integer
code: SELECT id, title, (substring(content, 1, {{max_length}}) || (CASE WHEN length(content) < {{max_length}} THEN '' else '...' END)) AS excerpt, date FROM article
returns: article_excerpt
native_queries:
- root_field_name: article_with_excerpt
arguments:
max_length:
type: integer
code:
SELECT id, title, (substring(content, 1, {{max_length}}) || (CASE WHEN length(content) < {{max_length}} THEN ''
else '...' END)) AS excerpt, date FROM article
returns: article_excerpt
```
</TabItem>
@ -303,11 +307,13 @@ Click on the `Logical Models` tab, and on the `Add Logical Model` button.
Once the modal is open, fill in the forms with:
- The database to use as source
- The Logical Model name
- The optional input fields
| Field | Value |
| ------------------ | ----------------------------- |
| Source | The database to be used |
| Logical Model Name | The name of the Logical Model |
<Thumbnail src="/img/native-queries/logical-model-modal.png" alt="Create Logical Model" width="800px" />
Finally, add any optional fields that you would like to be included in the Logical Model and click
`Create Logical Model`.
</TabItem>
@ -368,14 +374,17 @@ Click on the `Native Queries` tab and `Create Native Query` button.
<Thumbnail src="/img/native-queries/native-query-create.png" alt="Create Native Query" width="1146px" />
Fill in the form with the data required:
Then, fill in the form with the data required:
- Native Query name
- An optional comment
- The database to be used
- Optional input parameters to be send to the Native Query
- The Native Query statement
- The query return type (the Logical Model previously created)
| Field | Value |
| -------------------------- | ------------------------------- |
| Native Query name | `article_with_excerpt` |
| Database | The database to be used |
| Input parameter | `max_length`, of type `integer` |
| The Native Query statement | Your SQL statement. |
| Query Return Type | The Logical Model created above |
Finally, click `Save`.
<Thumbnail src="/img/native-queries/create-native-query.png" alt="Create Native Query Form" width="1146px" />
@ -449,13 +458,15 @@ X-Hasura-Role: admin
</TabItem>
</Tabs>
You can use any SQL that you could potentially use in a parameterized query, with the following caveats:
:::info You can use any SQL that you could potentially use in a parameterized query, with the following caveats
- The query must currently be a single read-only SQL query.
- The query must be a valid standalone query, and not a partial query.
- The return type of the query must match with the Logical Model.
- The SQL cannot invoke a stored procedure.
:::
#### Arguments
The query can take arguments, which are specified in the metadata. These arguments can be used in the SQL using the

BIN
docs/static/img/native-queries/create-logical-model-excerpt-example.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 91 KiB

After

Width:  |  Height:  |  Size: 60 KiB

BIN
docs/static/img/native-queries/delete-logical-model.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 41 KiB

After

Width:  |  Height:  |  Size: 48 KiB

BIN
docs/static/img/native-queries/delete-permissions.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 25 KiB

After

Width:  |  Height:  |  Size: 59 KiB

BIN
docs/static/img/native-queries/edit-logical-model-permissions.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 48 KiB

BIN
docs/static/img/native-queries/graphql-api-native-query.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 151 KiB

After

Width:  |  Height:  |  Size: 72 KiB

BIN
docs/static/img/native-queries/native-queries-menu.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 69 KiB

After

Width:  |  Height:  |  Size: 44 KiB

BIN
docs/static/img/native-queries/native-query-create.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 65 KiB

After

Width:  |  Height:  |  Size: 44 KiB