GraphQL Transform

Reference Documentation

@model

Object types that are annotated with @model are top level entities in the generated API. Objects annotated with @model are stored in DynamoDB and are capable of being protected via @auth, related to other objects via @connection, and streamed via @searchable.

Definition

1directive @model(queries: ModelQueryMap, mutations: ModelMutationMap) on OBJECT
2input ModelMutationMap {
3  create: String
4  update: String
5  delete: String
6}
7input ModelQueryMap {
8  get: String
9  list: String
10}

Usage

Define a GraphQL object type and annotate it with the @model directive to store objects of that type in DynamoDB and automatically configure CRUDL queries and mutations.

1type Post @model {
2  id: ID! # id: ID! is a required attribute.
3  title: String!
4  tags: [String!]!
5}

You may also override the names of any generated queries and mutations as well as remove operations entirely.

1type Post @model(queries: { get: "post" }, mutations: null) {
2  id: ID!
3  title: String!
4  tags: [String!]!
5}

This would create and configure a single query field post(id: ID!): Post and no mutation fields.

@auth

Object types that are annotated with @auth are protected by one of the supported authorization strategies. Types that are annotated with @auth must also be annotated with @model.

Definition

1# When applied to a type, augments the application with
2# owner and group based authorization rules.
3directive @auth(rules: [AuthRule!]!) on OBJECT
4
5input AuthRule {
6  allow: AuthStrategy!
7  ownerField: String = "owner"
8  identityField: String = "username"
9  groupsField: String
10  groups: [String]
11  queries: [ModelQuery]
12  mutations: [ModelMutation]
13}
14enum AuthStrategy {
15  owner
16  groups
17}
18enum ModelQuery {
19  get
20  list
21}
22enum ModelMutation {
23  create
24  update
25  delete
26}

Authorization Strategies

Owner Authorization

1# The simplest case
2type Post @model @auth(rules: [{ allow: owner }]) {
3  id: ID!
4  title: String!
5}
6
7# The long form way
8type Post @model @auth(rules: [{ allow: owner, ownerField: "owner", mutations: [create, update, delete], queries: [get, list] }]) {
9  id: ID!
10  title: String!
11  owner: String
12}

Owner authorization specifies that a user (or set of user's) can access an object. To do so, each object has an ownerField (by default "owner") that stores ownership information and is verified in various ways during resolver execution.

You may use the queries and mutations arguments to specify which operations are augmented:

get: If the record's owner is not the same as the logged in user (via $ctx.identity.username), throw $util.unauthorized(). list: Filter $ctx.result.items for owned items. create: Inject the logged in user's $ctx.identity.username as the ownerField automatically. update: Add conditional update that checks the stored ownerField is the same as $ctx.identity.username. delete: Add conditional update that checks the stored ownerField is the same as $ctx.identity.username.

IN PROGRESS

1# TODO: (WORK IN PROGRESS) Does not yet support multi-owner
2type Post @model @auth(rules: [{ allow: owner, ownerField: "owners", mutations: [create, update, delete], queries: [get, list] }]) {
3  id: ID!
4  title: String!
5  owners: [String]
6}

Group Authorization

Static Group Auth

1# Static group auth
2type Post @model @auth(rules: [{ allow: groups, groups: ["Admin"] }]) {
3  id: ID!
4  title: String
5}

If the user credential (as specified by the resolver's $ctx.identity) is not enrolled in the Admin group, throw an unauthorized error via $util.unauthorized().

Dynamic Group Auth

1# Dynamic group auth with multiple groups
2type Post @model @auth(rules: [{ allow: groups, groupsField: "groups" }]) {
3  id: ID!
4  title: String
5  groups: [String]
6}
7
8# Dynamic group auth with a single group
9type Post @model @auth(rules: [{ allow: groups, groupsField: "group" }]) {
10  id: ID!
11  title: String
12  group: String
13}

With dynamic group authorization, each record contains an attribute specifying what groups should be able to access it. Use the groupsField argument to specify which attribute in the underlying data store holds this group information. To specify that a single group should have access use a field of type String. To specify that multiple groups should have access use a field of type [String].

@connection

The @connection directive allows you to specify relationships between @model object types. Currently this supports one-to-one, one-to-many, and many-to-one relationships. An error will be thrown when trying to configure a many-to-many relationship.

Definition

1directive @connection(name: String) on FIELD_DEFINITION

Usage

Relationships are specified by annotating fields on an @model object type with the @connection directive.

Unnamed Connections

In the simplest case, you may define a one-to-one connection:

1type Project @model {
2  id: ID!
3  name: String
4  team: Team @connection
5}
6type Team @model {
7  id: ID!
8  name: String!
9}

Once transformed you would then be able to create projects with a team via:

1mutation CreateProject {
2  createProject(input: { name: "New Project", projectTeamId: "a-team-id" }) {
3    id
4    name
5    team {
6      id
7      name
8    }
9  }
10}

Note: The Project.team resolver will be preconfigured to work with the defined connection.

Likewise you may make a simple one-to-many connection:

1type Post {
2  id: ID!
3  title: String!
4  comments: [Comment] @connection
5}
6type Comment {
7  id: ID!
8  content: String!
9}

One transformed, you would create comments with a post via:

1mutation CreateCommentOnPost {
2  createComment(input: { content: "A comment", postCommentsId: "a-post-id" }) {
3    id
4    content
5  }
6}

Note: The "postCommentsId" field on the input may seem like a strange name and it is. In the one-to-many case without a provided "name" argument there is only partial information to work with resulting in the strange name. To fix this, provide a value for the @connection's name argument and complete the bi-directional relationship by adding a corresponding @connection field to the Comment type.

Named Connections

The name arguments specifies a name for the connection and is used to create bi-directional relationships that reference the same underlying foreign key.

For example, if you wanted your Post.comments and Comment.post fields to refer to opposite sides of the same relationship you would provide a name.

1type Post @model {
2  id: ID!
3  title: String!
4  comments: [Comment] @connection(name: "PostComments")
5}
6type Comment @model {
7  id: ID!
8  content: String!
9  post: Post @connection(name: "PostComments")
10}

One transformed, you would create comments with a post via:

1mutation CreateCommentOnPost {
2  createComment(input: { content: "A comment", commentPostId: "a-post-id" }) {
3    id
4    content
5    post {
6      id
7      title
8      comments {
9        id
10        # and so on...
11      }
12    }
13  }
14}

Performance

In order to keep connection queries fast and efficient, the graphql transform manages GSIs on the generated tables on your behalf. We bake in best practices to keep your queries efficient but this also comes with additional cost.

@searchable

The @searchable directive handles streaming the data of an @model object type and configures search resolvers that search that information.

Definition

1# Streams data from dynamodb into opensearch and exposes search capabilities.
2directive @searchable(queries: SearchableQueryMap) on OBJECT
3input SearchableQueryMap {
4  search: String
5}

What is the Amplify GraphQL Transform

The Amplify GraphQL Transform is a set of libraries committed to simplifying the process of developing, deploying, and maintaining APIs on AWS. With it, you define your API using the GraphQL Schema Definition Language (SDL) and then pass it to this library where it is expanded and transformed into a fully descriptive cloudformation template that implements your API's data model.

For example, you might define the data model for an app like this:

1type Blog @model @searchable {
2  id: ID!
3  name: String!
4  posts: [Post] @connection(name: "BlogPosts")
5}
6type Post @model @searchable {
7  id: ID!
8  title: String!
9  tags: [String]
10  blog: Blog @connection(name: "BlogPosts")
11  comments: [Comment] @connection
12  createdAt: String
13  updatedAt: String
14}
15type Comment @model {
16  id: ID!
17  content: String!
18}

And then pass the schema to an instance of the GraphQLTransform class with the DynamoDB, @searchable, and Connection transformers enabled:

1import GraphQLTransform from 'graphql-transformer-core';
2import AppSyncDynamoDBTransformer from 'graphql-dynamodb-transformer';
3import SearchableModelTransformer from 'amplify-graphql-searchable-transformer';
4import AppSyncConnectionTransformer from 'graphql-connection-transformer';
5import AppSyncAuthTransformer from 'graphql-auth-transformer';
6
7const transformer = new GraphQLTransform({
8  transformers: [
9    new AppSyncDynamoDBTransformer(),
10    new SearchableModelTransformer(),
11    new AppSyncAuthTransformer(),
12    new AppSyncConnectionTransformer(),
13  ],
14});
15const cfdoc = transformer.transform(schema.readSync());
16const out = await createStack(cfdoc, name, region);
17console.log('Application creation successfully started. It may take a few minutes to finish.');

The GraphQLTransform class implements a single transform() function that when invoked parses the document, walks the AST, and when a directive such as @model is found invokes any relevant transformers. In this case the transformers were defined for you but the code is structured to make writing custom transformers as simple as possible. The output of the above code is a full CloudFormation document that defines DynamoDB tables, an OpenSearch cluster, a lambda function to stream from DynamoDB -> OpenSearch, an AppSync API, AppSync data sources, CRUD resolvers (create, update, delete, get, list, search), resolvers that implement connections between types stored in different DynamoDB tables, a number of minimally scoped IAM roles,

GraphQL Transform Libraries

The code is contained in a mono-repo that includes a number of packages that are related to the transform and a number of packages that are not. The related packages are broken up as follows

graphql-transform

The package contains the core of the library and acts as the entry point to the transform. The core class GraphQLTransform takes as config a list of transformers and handles the logic that parses the input SDL, walks the AST, and routes directives to transformers.

graphql-dynamodb-transformer

This package implements a number of directives that deal with DynamoDB. Out of the box, this implements the @model and connection directives.

amplify-graphql-searchable-transformer

This package implements any directives that deal with a searchable data source. Out of the box, this implements the @searchable directive.

graphql-auth-transformer

This package implements any directives related to authN or authZ workflows. Out of the box, it configures an Amazon Cognito UserPool and implements the @auth directive.

graphql-transformer-e2e-tests

This pacakge implements end-to-end tests for the transform libraries. It builds an API with the transform, deploys it via CloudFormation, and hits the AppSync data plane to test all generated code paths.

graphql-mapping-template

This package provides a lightweight wrapper around the AppSync Resolver VTL and is used by transformer libraries as a convenience.

Prerequisites

• You will need to have nodejs and npm installed.
• You will then need to install lerna and yarn as npm global packages.

npm install -g lerna
npm install -g yarn

Installing

Install the dependencies

lerna bootstrap

And build

lerna run build

Running the tests

Tests are written with jest and can be run for all packages with

lerna run test

Alternatively, there are some debug configurations defined in .vscode/launch.json you can use Visual Studio code to add debug breakpoints to debug the code.

Contributing

TODO

Versioning

TODO

License

This project is licensed under the MIT License - see the LICENSE.md file for details