Skip to content

Commit

Permalink
Merge branch 'master' into patch-1
Browse files Browse the repository at this point in the history
  • Loading branch information
@gurukulkarni
gurukulkarni committed Jul 24, 2023
2 parents cbb261d + a833379 commit 0f2e8ee
Show file tree
Hide file tree
Showing 20 changed files with 400 additions and 294 deletions.
99 changes: 48 additions & 51 deletions docs/docs/schema/bigquery/logical-models/index.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand Down Expand Up @@ -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"
Expand All @@ -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>
Expand Down Expand Up @@ -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>

Expand Down Expand Up @@ -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">
Expand Down Expand Up @@ -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">
Expand Down Expand Up @@ -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).

Expand All @@ -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>
Expand Down
80 changes: 40 additions & 40 deletions docs/docs/schema/bigquery/logical-models/native-queries.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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.

:::

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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">
Expand Down Expand Up @@ -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.

:::

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

0 comments on commit 0f2e8ee

Please sign in to comment.