aws-amplifyGraphQL 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
directive @model(queries: ModelQueryMap, mutations: ModelMutationMap) on OBJECT
input ModelMutationMap {
create: String
update: String
delete: String
}
input ModelQueryMap {
get: String
list: String
}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.
type Post @model {
id: ID! # id: ID! is a required attribute.
title: String!
tags: [String!]!
}You may also override the names of any generated queries and mutations as well as remove operations entirely.
type Post @model(queries: { get: "post" }, mutations: null) {
id: ID!
title: String!
tags: [String!]!
}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
# When applied to a type, augments the application with
# owner and group based authorization rules.
directive @auth(rules: [AuthRule!]!) on OBJECT
input AuthRule {
allow: AuthStrategy!
ownerField: String = "owner"
identityField: String = "username"
groupsField: String
groups: [String]
queries: [ModelQuery]
mutations: [ModelMutation]
}
enum AuthStrategy {
owner
groups
}
enum ModelQuery {
get
list
}
enum ModelMutation {
create
update
delete
}Authorization Strategies
Owner Authorization
# The simplest case
type Post @model @auth(rules: [{ allow: owner }]) {
id: ID!
title: String!
}
# The long form way
type Post @model @auth(rules: [{ allow: owner, ownerField: "owner", mutations: [create, update, delete], queries: [get, list] }]) {
id: ID!
title: String!
owner: String
}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
# TODO: (WORK IN PROGRESS) Does not yet support multi-owner
type Post @model @auth(rules: [{ allow: owner, ownerField: "owners", mutations: [create, update, delete], queries: [get, list] }]) {
id: ID!
title: String!
owners: [String]
}Group Authorization
Static Group Auth
# Static group auth
type Post @model @auth(rules: [{ allow: groups, groups: ["Admin"] }]) {
id: ID!
title: String
}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
# Dynamic group auth with multiple groups
type Post @model @auth(rules: [{ allow: groups, groupsField: "groups" }]) {
id: ID!
title: String
groups: [String]
}
# Dynamic group auth with a single group
type Post @model @auth(rules: [{ allow: groups, groupsField: "group" }]) {
id: ID!
title: String
group: String
}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
directive @connection(name: String) on FIELD_DEFINITIONUsage
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:
type Project @model {
id: ID!
name: String
team: Team @connection
}
type Team @model {
id: ID!
name: String!
}Once transformed you would then be able to create projects with a team via:
mutation CreateProject {
createProject(input: { name: "New Project", projectTeamId: "a-team-id" }) {
id
name
team {
id
name
}
}
}Note: The Project.team resolver will be preconfigured to work with the defined connection.
Likewise you may make a simple one-to-many connection:
type Post {
id: ID!
title: String!
comments: [Comment] @connection
}
type Comment {
id: ID!
content: String!
}One transformed, you would create comments with a post via:
mutation CreateCommentOnPost {
createComment(input: { content: "A comment", postCommentsId: "a-post-id" }) {
id
content
}
}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.
type Post @model {
id: ID!
title: String!
comments: [Comment] @connection(name: "PostComments")
}
type Comment @model {
id: ID!
content: String!
post: Post @connection(name: "PostComments")
}One transformed, you would create comments with a post via:
mutation CreateCommentOnPost {
createComment(input: { content: "A comment", commentPostId: "a-post-id" }) {
id
content
post {
id
title
comments {
id
# and so on...
}
}
}
}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
# Streams data from dynamodb into opensearch and exposes search capabilities.
directive @searchable(queries: SearchableQueryMap) on OBJECT
input SearchableQueryMap {
search: String
}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:
type Blog @model @searchable {
id: ID!
name: String!
posts: [Post] @connection(name: "BlogPosts")
}
type Post @model @searchable {
id: ID!
title: String!
tags: [String]
blog: Blog @connection(name: "BlogPosts")
comments: [Comment] @connection
createdAt: String
updatedAt: String
}
type Comment @model {
id: ID!
content: String!
}And then pass the schema to an instance of the GraphQLTransform class with the DynamoDB, @searchable, and Connection transformers enabled:
import GraphQLTransform from 'graphql-transformer-core';
import AppSyncDynamoDBTransformer from 'graphql-dynamodb-transformer';
import SearchableModelTransformer from 'amplify-graphql-searchable-transformer';
import AppSyncConnectionTransformer from 'graphql-connection-transformer';
import AppSyncAuthTransformer from 'graphql-auth-transformer';
const transformer = new GraphQLTransform({
transformers: [
new AppSyncDynamoDBTransformer(),
new SearchableModelTransformer(),
new AppSyncAuthTransformer(),
new AppSyncConnectionTransformer(),
],
});
const cfdoc = transformer.transform(schema.readSync());
const out = await createStack(cfdoc, name, region);
console.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
lernaandyarnas npm global packages.
npm install -g lerna
npm install -g yarnInstalling
Install the dependencies
lerna bootstrapAnd build
lerna run buildRunning the tests
Tests are written with jest and can be run for all packages with
lerna run testAlternatively, 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