Models
Introduction
Models are the link between your data connectors and the API Hasura generates. A model may be backed by a database table, an ad-hoc SQL query, a pre-materialized view, a custom REST or GraphQL API server, etc.
It's helpful to think of models as your way of telling Hasura how to interact with your data. They define how to
query your data, how it's related, and how to interact with it. Once a model is declared it will then often be
referenced by Relationship and/or Permissions objects.
When using ddn dev, the CLI will automatically track tables in your database as models after generating their
types. However, you can also use define these models manually in your metadata.
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. |
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. |
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. |
Example:
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
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 |
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
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
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> | string | false |
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