Skip to main content
Version: v2.x

Postgres: Logical Models

Introduction

Supported from
  • Hasura Cloud: v2.26.0.
  • Hasura Enterprise Edition: v2.26.0.
  • Hasura Community Edition: v2.28.0.

Logical Models are a GraphQL representation of database data. They provide an abstraction over the underlying database.

Logical Models are a new approach from Hasura and are currently used by the Native Queries feature to automatically create a GraphQL API for a native database query.

You can find examples of how to use Logical Models in the Native Queries documentation. For a more detailed explanation of Logical Models themselves, read on.

Tracking a Logical Model

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:

Create Logical Model

The type of each field can be either a PostgreSQL data type or references to other Logical Models, and each field can be marked as nullable or not, see LogicalModelType.

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:

Create Logical Model

Untracking a Logical Model

To untrack a Logical Model, click Remove next to the Logical Model:

Delete Logical Model
Removing a Logical Model

Note that you can only remove an unused Logical Model; if the model is attached to a Native Query, this operation will fail. You must remove the Native Query first.

To untrack the above article Logical Model, we would run the following:

Delete Logical Model

Referencing other Logical Models

Logical Model fields are allowed to refer to other Logical Models, even recursively, allowing nested data types.

To elaborate on the article example above, we can include authors in the data model:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
"type": "bulk_atomic",
"args":
[
{
"type": "pg_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": "pg_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"
}
}
}
]
}
}
]
}
Wrap calls in bulk_atomic

Tracking the Logical Models one-by-one would fail, since article refers to author, which is not yet defined.

Tracking the Logical Models in one atomic operation postpones coherency checks until all models are tracked, which allows for mutual references.

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 adding permissions for a given role.

As Logical Models are currently only used for read-only purposes, you can only add select permissions.

The permissions consist of a list of columns that the role can access, and a filter that specifies which rows the role can receive.

Create Logical Model Permissions

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

Permissions with check

You can also drop permissions:

Delete Permissions