Version: 1.0

Annotations

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

Let's have a look at a simple Note data model.

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

This will generate all the API definitions, resolvers, services and data providers.

"""
@model
"""
type Note {
id: ID!
text: String
description: String
}
type Query {
getNote(id: ID!): Note
findNotes(filter: NoteFilter, page: PageRequest, orderBy: OrderByInput): NoteResultList!
}
type Mutation {
createNote(input: CreateNoteInput!): Note
updateNote(input: MutateNoteInput!): Note
deleteNote(input: MutateNoteInput!): Note
}
type Subscription {
newNote(filter: NoteSubscriptionFilter): Note!
updatedNote(filter: NoteSubscriptionFilter): Note!
deletedNote(filter: NoteSubscriptionFilter): Note!
}

You can customise what gets generated per model by adding arguments. This example tells Graphback to generate all resolvers except the deleteNote mutation and deletedNote.

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

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)

@oneToMany

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

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

This will generate the an author field on the Post to model to enable bidirectional querying.

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

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

@oneToOne

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

"""@model"""
type Character {
id:ID!
name: String!
"""@oneToOne"""
cast_actor: Actor!
}
"""@model"""
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.

Arguments

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

@index

The @index annotation can be used to create an index on a specific field or a set of fields at runtime. The supported arguments are different between the different databases. See the variations for PostgreSQL and MongoDB.

@transient

The @transient field annotation omits this field from the generated inputs Create<T>Input, <T>Filter, <T>SubscriptionFilter and Mutate<T>Input.

"""@model"""
type User {
id: ID!
name: String
"""@transient"""
computedField: String
}

PostgreSQL

@id

You can customise the default primary key field with the @id annotation.

"""@model"""
type User {
id: ID!
"""@id"""
username: String!
}

@index

The @index annotation can be used with GraphQL Migrations to create indexes on your PostgreSQL database tables.

You can create one or multiple indexes per table.

"""@model"""
type User {
id: ID!
"""
@index
"""
name: String!
"""
@index(name: 'userEmail_Idx', type: 'hash')
"""
email: String!
}

This creates two custom indexes on the user table:

"user_name_index" btree (name)
"userEmail_index" hash (email)

You can also create a composite index.

"""@model"""
type User {
id: ID!
"""
@index(name: 'user_unique_index')
"""
email: String!
"""
@index(name: 'user_unique_index')
"""
name: String!
}

This creates the following composite index:

"user_unique_index" btree (email, name)

Arguments

ArgumentDescriptionExample
nameSpecifies the name of index. Optional. Defaults to <tablename>_<columnname>_index. Accepts a string value@index(name: 'myIndex')
typeSpecifies the index type. Optional. Accepts a string value. Supported values: btree (default), hash, gist, spgist, gin and brin@index(type: 'hash')

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.

@db

GraphQL Migrations is a library to perform database migrations tables for PostgreSQL using a GraphQL schema. Most of the migration operations can be specified with the @db annotation. Check out the documentation for GraphQL Migrations to learn more.

@default

The @default annotation is used to specify a default value. This is currently only supported for PostgreSQL through the GraphQL Migrations package.

"""@model"""
type User {
id: ID!
"""@default(value: false)"""
verified: Boolean!
}

Arguments

ArgumentDescriptionExample
valueSpecifies the default value for the field. Required.@default(value: 1)

MongoDB

@index

The @index annotation can be used to create an index on a specific field or a set of fields at runtime.

You can create one or multiple indexes per collection.

"""
@model
"""
type Comment {
id: ID!
"""
Add an index with a generated name
@index
"""
text: String
"""
Creating a custom named index
@index(
name: 'descriptionIndex'
)
"""
description: String
}

You can also create a compound index with they key property (see Arguments for an explanation of how to use it).

"""@model"""
type User {
id: ID!
"""
@index(
name: 'user_unique_index',
key: {
email: 1,
name: 1
}
)
"""
email: String!
name: String!
}

Graphback creates the following indexes on the user collection in the Mongo database users:

{
"v" : 2,
"key" : {
"email" : 1,
"name" : 1
},
"name" : "user_unique_index",
"ns" : "users.user"
}

Arguments

ArgumentDescriptionType
keySpecifies the index’s fields. For each field, specify a key-value pair in which the key is the name of the field to index and the value is either the index direction or index type. If specifying direction, specify 1 for ascending or -1 for descending. For example: { text: 1, description: 1 }
nameOptional. A name that uniquely identifies the index.string
uniqueOptional. Creates a unique index so that the collection will not accept insertion or update of documents where the index key value matches an existing value in the index.

Specify true to create a unique index. The default value is false.
boolean

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.

@versioned

The @versioned annotation adds two fields to a model: updatedAt and createdAt to track the documents's last updated and created at timestamps. The fields are then automatically managed and updated by Graphback.

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

This generates the following GraphQL type:

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