GraphQL Entities

• Introduction
• Overview of GraphQL Entities
• Creating Data Provider Entities
• Defining GraphQL Entities for Different Data Providers
• Creating GraphQL Entities
• Customising GraphQL Entities
• Field Resolver
• Conclusion

Introduction

GraphQL entities play a vital role in Graphweaver. They are responsible for defining the data schema and handling data operations in GraphQL APIs.

By understanding how to create and customise these entities, you can unleash the full potential of GraphQL in your applications.

Overview of GraphQL Entities

In GraphQL, entities represent the objects or data types in your system. They define the fields and relationships that can be queried and mutated.

They are also responsible for connecting the data provider to Graphweaver which resolves the queries and mutations against the underlying data sources.

GraphWeaver simplifies the creation and integration of entities by providing a set of tools and abstractions. It allows you to define entities for different data providers, such as databases (MySQL, PostgreSQL) and external services (REST, Xero). You can connect these entities to the GraphQL layer and map data sources to GraphQL attributes.

Creating Data Provider Entities

To start with, you need to create entities in the respective data providers. For example, if you're working with a MySQL database, you would create a database entity to represent a table. This entity defines the attributes and structure of the data in the database.

There is more on this in the data entities section.

For this example we will look to create a GraphQL entity for a Task data entity. This data entity is a table held in MySQL database, it looks like this:

import { BigIntType, Entity, PrimaryKey, Property } from '@mikro-orm/core';
import { BaseEntity, ExternalIdField } from '@exogee/graphweaver-mikroorm';

@Entity()
export class Task extends BaseEntity {
	@PrimaryKey({ type: BigIntType })
	id!: string;

	@Property({ type: String })
	description!: string;

	@ExternalIdField({ from: 'user' })
	@Property({ type: BigIntType })
	userId!: string;
}

Now we have defined the data entity we can attach it to a GraphQL entity.

Defining GraphQL Entities for Different Data Providers

In Graphweaver, you can define GraphQL entities to expose the data from the data providers. The process involves creating GraphQL entities that correspond to the data provider entities. Let’s look at connecting the Task data entity from above.

Creating GraphQL Entities

To expose the data provider entity, you need to create a GraphQL entity in your project. This entity represents the data structure that will be exposed through the GraphQL API.

Start by creating a new directory in ./src/schema for the entity. Inside this directory, create an entity.ts file that defines the attributes that will be exposed in the GraphQL API and connects the GraphQL entity to the data provider entity.

For example, let's create a Task GraphQL entity:

import { GraphQLEntity, RelationshipField, Field, ID, Entity } from '@exogee/graphweaver';
import { MikroBackendProvider } from '@exogee/graphweaver-mikroorm';

import { Task as OrmTask } from '../entities';
import { User } from './user';
import { myConnection } from '../database';

@Entity('Task', {
	provider: new MikroBackendProvider(OrmTask, myConnection),
})
export class Task extends GraphQLEntity<OrmTask> {
	public dataEntity!: OrmTask;

	@Field(() => ID)
	id!: string;

	@Field(() => String)
	description!: string;

	@Field(() => Boolean)
	isCompleted!: boolean;

	@RelationshipField<Task>(() => User, { id: 'userId' })
	user!: User;
}

In the above code, we define the Task GraphQL entity by extending the GraphQLEntity class and specifying the corresponding data provider entity (OrmTask this is the Tasks data entity we created earlier). The attributes are decorated with @Field to expose them in the GraphQL schema. For more on decorators and their usage see the decorators section.

Now we have a Data Provider Entity and a GraphQL Entity. The next task is to create a resolver that will be used by the Queries and Mutations.

Customising GraphQL Entities

There may be cases where you need to extend an entity with custom queries or mutations.

Graphweaver allows you to create custom queries and mutations in addition to the ones provided automatically.

Field Resolver

Sometimes you will have a requirement to combine two attributes or to compute a new property. To do this you can use a Field Resolver. Here is an example of returning two combined values for the Task entity and creating a new property called slug:

import { GraphQLEntity, RelationshipField, Field, ID, Entity } from '@exogee/graphweaver';
import { MikroBackendProvider } from '@exogee/graphweaver-mikroorm';

import { Task as OrmTask } from '../entities';
import { User } from './user';
import { myConnection } from '../database';

@Entity('Task', {
	provider: new MikroBackendProvider(OrmTask, myConnection),
})
export class Task extends GraphQLEntity<OrmTask> {
	public dataEntity!: OrmTask;

	@Field(() => ID)
	id!: string;

	@Field(() => String)
	description!: string;

	@Field(() => Boolean)
	isCompleted!: boolean;
	
	@Field(type => String, { nullable: true })
	slug(task: Task) {
		return `${task.id}:${task.description}`;
	}

	@RelationshipField<Task>(() => User, { id: 'userId' })
	user!: User;
}

As you can see from the above the field resolver is a function, in here you can do any logic required to return the computed value.

Conclusion

In this article, we explored the creation and customisation of GraphQL entities in Graphweaver.

We learned how to create data provider entities, define GraphQL entities for different data providers, connect them to the data sources.

Additionally, we explored the process of adding custom queries and mutations to extend the functionality of the API.

By leveraging the power of GraphQL entities, you can build robust and scalable GraphQL APIs that seamlessly integrate with various data providers. Graphweaver simplifies this process by providing a unified framework and tools to handle the complexities of data operations.

Start implementing GraphQL entities in your Graphweaver projects and unlock the full potential of GraphQL in your applications.