Models
Introduction
A "Model" in Hasura DDN represents a collection of data objects (eg: Users
). Models can have "operations"
defined on them so that they can be inserted, edited, deleted or fetched (with filtering, pagination, sorting, etc.).
Very loosely, you can think of models as the nouns, or "things" of your data domain.
Models as the link between a data connector and the API that Hasura generates. Models can be backed by various data sources such as a database table, an ad-hoc SQL query, a pre-materialized view, or a custom REST or GraphQL API server.
Once a model is declared it will then often be referenced by Relationship
objects in order to compose them with
each other or commands, and also by Permissions
objects to control access to the data.
View an example of a model and an API query it enables
The following is an example of a model definition for a Users
model. This model is backed by a Postgres data:
---
kind: Model
version: v1
definition:
name: Users
objectType: Users
source:
dataConnectorName: my_pg
collection: users
filterExpressionType: UsersBoolExp
orderableFields:
- fieldName: createdAt
orderByDirections:
enableAll: true
- fieldName: email
orderByDirections:
enableAll: true
- fieldName: favoriteArtist
orderByDirections:
enableAll: true
- fieldName: id
orderByDirections:
enableAll: true
- fieldName: isEmailVerified
orderByDirections:
enableAll: true
- fieldName: lastSeen
orderByDirections:
enableAll: true
- fieldName: name
orderByDirections:
enableAll: true
- fieldName: password
orderByDirections:
enableAll: true
- fieldName: updatedAt
orderByDirections:
enableAll: true
graphql:
selectMany:
queryRootField: mySubgraph_users
selectUniques:
- queryRootField: mySubgraph_usersById
uniqueIdentifier:
- id
orderByExpressionType: MySubgraph_UsersOrderBy
The above model definition enables the following query in the API:
query UsersQuery {
mySubgraph_users(
where: {favoriteArtist: {_eq: "1"}}
order_by: {name: Asc}
limit: 10
) {
id
createdAt
updatedAt
name
email
isEmailVerified
password
lastSeen
favoriteArtist
}
}
Check out Global IDs for relay:
A Global ID is a unique identifier for an object across the entire application, not just within a specific table or type. Think of it as an ID which you can use to fetch any object directly, regardless of what kind of object it is. This is different from typical database IDs, which are often guaranteed unique only within a particular table.
Hasura's Global ID implementation can be used to provide options for GraphQL clients to elegantly handle caching and data re-fetching in a predictable and standardized way.
The Global ID generated by Hasura DDN follows the Relay Global ID spec.
As the example below shows, the user
object type has a field user_id
that uniquely identifies a user. The Global ID
for the user
object type will be generated using the user_id
field:
For the following request on a model which has enabled Global ID:
{
user_by_id(user_id: 1) {
id // Global ID
user_id
name
}
}
The response obtained should look like the following:
{
"data": {
"user_by_id": {
"id": "eyJ2ZXJzaW9uIjoxLCJ0eXBlbmFtZSI6IkFydGljbGUiLCJpZCI6eyJhcnRpY2xlX2lkIjoyfX0=",
"user_id": 1,
"name": "Bob"
}
}
}
Now, with the Global ID received above, the User
object corresponding to user_id: 1
can be retrieved, as shown
below.
{
node(id: "eyJ2ZXJzaW9uIjoxLCJ0eXBlbmFtZSI6IkFydGljbGUiLCJpZCI6eyJhcnRpY2xlX2lkIjoyfX0=") {
id
__typename
... on User {
name
}
}
}
The response to the above request should identify the User
with user_id: 1
.
{
"node": {
"id": "eyJ2ZXJzaW9uIjoxLCJ0eXBlbmFtZSI6IkFydGljbGUiLCJpZCI6eyJhcnRpY2xlX2lkIjoyfX0=",
"__typename": "User",
"name": "Bob"
}
}
Metadata structure
Model
The definition of a data model. A data model is a collection of objects of a particular type. Models can support one or more CRUD operations.
Key | Value | Required | Description |
---|---|---|---|
kind | Model | true | |
version | v1 | true | |
definition | ModelV1 | true | The definition of a data model. A data model is a collection of objects of a particular type. Models can support one or more CRUD operations. |
Example:
kind: Model
version: v1
definition:
name: Articles
objectType: article
globalIdSource: true
arguments: []
source:
dataConnectorName: data_connector
collection: articles
argumentMapping: {}
filterExpressionType: Article_bool_exp
orderableFields:
- fieldName: article_id
orderByDirections:
enableAll: true
- fieldName: title
orderByDirections:
enableAll: true
- fieldName: author_id
orderByDirections:
enableAll: true
graphql:
selectUniques:
- queryRootField: ArticleByID
uniqueIdentifier:
- article_id
description: Description for the select unique ArticleByID
selectMany:
queryRootField: ArticleMany
description: Description for the select many ArticleMany
orderByExpressionType: Article_Order_By
apolloFederation:
entitySource: true
description: Description for the model Articles
ModelV1
The definition of a data model. A data model is a collection of objects of a particular type. Models can support one or more CRUD operations.
Key | Value | Required | Description |
---|---|---|---|
name | ModelName | true | The name of the data model. |
objectType | CustomTypeName | true | The type of the objects of which this model is a collection. |
globalIdSource | boolean | false | Whether this model should be used as the global ID source for all objects of its type. |
arguments | [ArgumentDefinition] | false | A list of arguments accepted by this model. Defaults to no arguments. |
source | ModelSource / null | false | The source configuration for this model. |
filterExpressionType | CustomTypeName / null | false | The boolean expression type that should be used to perform filtering on this model. |
orderableFields | [OrderableField] | true | A list of fields that can be used to order the objects in this model. |
aggregateExpression | AggregateExpressionName / null | false | The name of the AggregateExpression that defines how to aggregate over this model |
graphql | ModelGraphQlDefinition / null | false | Configuration for how this model should appear in the GraphQL schema. |
description | string / null | false | The description of the model. Gets added to the description of the model in the graphql schema. |
ModelGraphQlDefinition
The definition of how a model appears in the GraphQL API.
Key | Value | Required | Description |
---|---|---|---|
selectUniques | [SelectUniqueGraphQlDefinition] | true | For each select unique defined here, a query root field is added to the GraphQL API that can be used to select a unique object from the model. |
selectMany | SelectManyGraphQlDefinition / null | false | Select many configuration for a model adds a query root field to the GraphQl API that can be used to retrieve multiple objects from the model. |
argumentsInputType | GraphQlTypeName / null | false | The type name of the input type used to hold the arguments of the model. |
orderByExpressionType | GraphQlTypeName / null | false | The type name of the order by expression input type. |
apolloFederation | ModelApolloFederationConfiguration / null | false | Apollo Federation configuration |
filterInputTypeName | GraphQlTypeName / null | false | The type name of the input type used to hold the filtering settings used by aggregates (etc) to filter their input before processing |
aggregate | ModelAggregateGraphQlDefinition / null | false | Configures the query root field added to the GraphQL API that can be used to aggregate over the model |
Example:
selectUniques:
- queryRootField: ArticleByID
uniqueIdentifier:
- article_id
description: Description for the select unique ArticleByID
selectMany:
queryRootField: ArticleMany
description: Description for the select many ArticleMany
orderByExpressionType: Article_Order_By
aggregate:
queryRootField: ArticleAggregate
description: Aggregate over Articles
ModelAggregateGraphQlDefinition
Key | Value | Required | Description |
---|---|---|---|
queryRootField | GraphQlFieldName | true | The name of the query root field for this API. |
description | string / null | false | The description of the aggregate graphql definition of the model. Gets added to the description of the aggregate root field of the model in the graphql schema. |
deprecated | Deprecated / null | false | Whether this aggregate query field is deprecated. If set, the deprecation status is added to the aggregate root field's graphql schema. |
ModelApolloFederationConfiguration
Key | Value | Required | Description |
---|---|---|---|
entitySource | boolean | true | Whether this model should be used as the source for fetching _entity for object of its type. |
GraphQlTypeName
Value: string
SelectManyGraphQlDefinition
The definition of the GraphQL API for selecting rows from a model.
Key | Value | Required | Description |
---|---|---|---|
queryRootField | GraphQlFieldName | true | The name of the query root field for this API. |
description | string / null | false | The description of the select many graphql definition of the model. Gets added to the description of the select many root field of the model in the graphql schema. |
deprecated | Deprecated / null | false | Whether this select many query field is deprecated. If set, the deprecation status is added to the select many root field's graphql schema. |
SelectUniqueGraphQlDefinition
The definition of the GraphQL API for selecting a unique row/object from a model.
Key | Value | Required | Description |
---|---|---|---|
queryRootField | GraphQlFieldName | true | The name of the query root field for this API. |
uniqueIdentifier | [FieldName] | true | A set of fields which can uniquely identify a row/object in the model. |
description | string / null | false | The description of the select unique graphql definition of the model. Gets added to the description of the select unique root field of the model in the graphql schema. |
deprecated | Deprecated / null | false | Whether this select unique query field is deprecated. If set, the deprecation status is added to the select unique root field's graphql schema. |
Deprecated
OpenDd configuration to indicate whether an object type field, relationship, model root field or command root field is deprecated.
Key | Value | Required | Description |
---|---|---|---|
reason | string / null | false | The reason for deprecation. |
GraphQlFieldName
The name of a GraphQL object field.
Value: string
AggregateExpressionName
The name of an aggregate expression.
Value: string
OrderableField
Key | Value | Required | Description |
---|---|---|---|
fieldName | FieldName | true | |
orderByDirections | EnableAllOrSpecific | true |
EnableAllOrSpecific
Must have exactly one of the following fields:
Key | Value | Required | Description |
---|---|---|---|
enableAll | boolean | false | |
enableSpecific | [OrderByDirection] | false |
OrderByDirection
Value: Asc
/ Desc
FieldName
The name of a field in a user-defined object type.
Value: string
ModelSource
Description of how a model maps to a particular data connector
Key | Value | Required | Description |
---|---|---|---|
dataConnectorName | DataConnectorName | true | The name of the data connector backing this model. |
collection | string | true | The collection in the data connector that backs this model. |
argumentMapping | ArgumentMapping | false | Mapping from model argument names to data connector collection argument names. |
Example:
dataConnectorName: data_connector
collection: articles
ArgumentMapping
Mapping of a comand or model argument name to the corresponding argument name used in the data connector. The key of this object is the argument name used in the command or model and the value is the argument name used in the data connector.
Key | Value | Required | Description |
---|---|---|---|
<customKey> | DataConnectorArgumentName | false |
DataConnectorArgumentName
Value: string
DataConnectorName
The name of a data connector.
Value: string
ArgumentDefinition
The definition of an argument for a field, command, or model.
Key | Value | Required | Description |
---|---|---|---|
name | ArgumentName | true | |
type | TypeReference | true | |
description | string / null | false |
TypeReference
A reference to an Open DD type including nullable values and arrays. Suffix '!' to indicate a non-nullable reference, and wrap in '[]' to indicate an array. Eg: '[String!]!' is a non-nullable array of non-nullable strings.
Value: string
ArgumentName
Value: string
CustomTypeName
The name of a user-defined type.
Value: string
ModelName
The name of data model.
Value: string