Version: next

Graphback Supported Metadata

Graphback uses graphql-metadata for model transformations at runtime.

Below is a list of annotations supported by Graphback:

@model

The @model annotation is at the core of the Graphback's model definition syntax. It tells Graphback if a type should be considered part of the data model i.e. a table in a relational database or a collection in MongoDB.

It also tells Graphback about what queries and mutations it needs to generate for a type. For Graphback to autogenerate type definitions and resolvers, there must be at least one type annotated with @model.

Arguments

ArgumentDescriptionExample
createOptionally specifies whether a create mutation is to be generated. Supported values: true, false. Defaults to true@model(create: false)
deleteOptionally specifies whether a delete mutation is to be generated. Supported values: true, false. Defaults to true@model(delete: true)
findOptionally specifies whether a find query is to be generated. Supported values: true, false. Defaults to true@model(find: false)
findOneOptionally specifies whether a findOne query is to be generated. Supported values: true, false. Defaults to true@model(findOne: false)
updateOptionally specifies whether a update mutation is to be generated. Supported values: true, false. Defaults to true@model(update: true)
subCreateOptionally specifies whether a new subscription is to be generated. Supported values: true, false. Defaults to true@model(subCreate: false)
subUpdateOptionally specifies whether an updated subscription is to be generated. Supported values: true, false. Defaults to true@model(subUpdate: false)
subDeleteOptionally specifies whether a deleted subscription is to be generated. Supported values: true, false. Defaults to true@model(subDelete: false)

Example

With the following example data model:

"""
@model(
delete: false
)
"""
type Comment {
id: ID!
text: String
description: String
}

Graphback generates the following queries, mutations and subscriptions:

type Mutation {
createComment(input: CreateCommentInput!): Comment!
updateComment(input: MutateCommentInput!): Comment!
}
type Query {
getComment(id: ID!): Comment
findComments(
filter: CommentFilter
page: PageRequest
orderBy: OrderByInput
): CommentResultList!
}
type Subscription {
newComment(filter: CommentSubscriptionFilter): Comment!
updatedComment(filter: CommentSubscriptionFilter): Comment!
}

In the above schema generated by Graphback, Comment type does not have a delete mutation or a deleted subscription.

@id

@id is used to specify a custom primary key. It takes no arguments.

Example

type Comment {
id: ID!
"""@id"""
username: String!
}

@default

The @default annotation is used to specify a default value. This is currently only supported for PostgreSQL database through the graphql-migrations package.

Arguments

ArgumentDescription
valueSpecifies the value that the field will take as a defaut value in the database. Required.

Example

type Comment {
id: ID!
"""
@default(value: '')
"""
text: String
}

@oneToMany

@oneToMany is used to define a One To Many relationship.

Arguments

ArgumentDescriptionExample
fieldSpecifies the name of resolver field on the foreign object. Required. Accepts a string value@oneToMany(field: 'user')
keyOptionally specifies the name of foreign key field on the foreign object. Accepts a string value. Defaults to <typeName>Id@oneToMany(field: 'user', key: 'user_key')

Example

"""mode"""
type User {
id:ID!
"""@oneToMany(field: 'author')"""
posts: [Post]
}
"""@model"""
type Post {
id:ID!
text: String!
}

This example generates an author field on the Post type with a User resolver as well as a userId field internally which can be used to query across relationships.

"""@model"""
type Post {
id:ID!
text: String!
author: User
}

@oneToOne

@oneToOne is used to define a One To One relationship.

Arguments

ArgumentDescriptionExample
keyOptionally specifies the name of foreign key field on the foreign object. Accepts a string value. Defaults to <typeName>Id@oneToMany(field: 'user', key: 'user_key')

Example

type Character {
id:ID!
name: String!
"""@oneToOne"""
cast_actor: Actor!
}
type Actor { ... }

This example generates an character field on the Actor type with a Character resolver as well as a characterId field internally which can be used to query across relationships.

Datasource specific annotations

@db

GraphQL migrations is a tool to create and update database tables for using relational databases with Graphback. It supports a ton of features by using the @db annotation. Please check this page for complete documentation of it's features. This feature is only supported by Knex supported data sources.

@versioned

The versioned annotation adds two fields to a model: updatedAt and createdAt which are then automatically managed by graphback. This annotation is only supported by the MongoDB data source as of now.

Example

From following example data model:

"""
@model
@versioned
"""
type Comment {
id: ID!
text: String
description: String
}

Graphback autogenerates the following:

type Comment {
id: ID!
text: String
description: String
note: Note
createdAt: String
updatedAt: String
}

@index

The @index annotation can be used to create an index on a specific field or a set of fields at runtime. This annotation is only supported by the MongoDB data source as of now. Note that if you have relationships in your models, the relevant foreign keys are automatically indexed by Graphback, so you do not have to index them using @index. Similarly, custom primary keys marked with @id are also automatically indexed by Graphback.

Arguments

The arguments provided to @index are parsed into an Index Definition object and then passed to db.collection.createIndexes.

Example

From following example data model:

"""
@model
"""
type Comment {
id: ID!
"""
@index
"""
text: String
"""
@index(
name: 'compound_index',
key: {
text: 1,
description: 1
}
)
"""
description: String
}

Graphback creates the following indexes on the collection comment in a db (say testdb):

{
"v" : 2,
"key" : {
"text" : 1
},
"name" : "text_1",
"ns" : "testdb.comment"
},
{
"v" : 2,
"key" : {
"text" : 1,
"description" : 1
},
"name" : "compound_index",
"ns" : "testdb.comment"
}