docs: improve logical model and native queries docs
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
@ -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>
|
||||
|
@ -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>
|
||||
|
@ -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>
|
||||
|
@ -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>
|
||||
|
@ -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>
|
||||
|
@ -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
|
||||
|
Before Width: | Height: | Size: 91 KiB After Width: | Height: | Size: 60 KiB |
Before Width: | Height: | Size: 41 KiB After Width: | Height: | Size: 48 KiB |
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
After Width: | Height: | Size: 48 KiB |
Before Width: | Height: | Size: 151 KiB After Width: | Height: | Size: 72 KiB |
Before Width: | Height: | Size: 69 KiB After Width: | Height: | Size: 44 KiB |
Before Width: | Height: | Size: 65 KiB After Width: | Height: | Size: 44 KiB |