Overview

You are currently viewing the legacy GraphQL Transformer documentation. View latest documentation

The GraphQL Transform provides a simple to use abstraction that helps you quickly create backends for your web and mobile applications on AWS. With the GraphQL Transform, you define your application's data model using the GraphQL Schema Definition Language (SDL) and the library handles converting your SDL definition into a set of fully descriptive AWS CloudFormation templates that implement your data model.

For example you might create the backend for a blog like this:

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

The GraphQL Transform simplifies the process of developing, deploying, and maintaining GraphQL APIs. With it, you define your API using the GraphQL Schema Definition Language (SDL) and can then use automation to transform it into a fully descriptive cloudformation template that implements the spec. The transform also provides a framework through which you can define your own transformers as @directives for custom workflows.

Create a GraphQL API

Navigate into the root of a JavaScript, iOS, or Android project and run:

1amplify init

Follow the wizard to create a new app. After finishing the wizard run:

1amplify add api

Select the following options:

Select GraphQL
When asked if you have a schema, say No
Select one of the default samples; you can change this later
Choose to edit the schema and it will open the new schema.graphql in your editor

You can leave the sample as is or try this schema.

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

Once you are happy with your schema, save the file and hit enter in your terminal window. if no error messages are thrown this means the transformation was successful and you can deploy your new API.

1amplify push

Test the API

Once the API is finished deploying, go to the AWS AppSync console or run amplify mock api to try some of these queries in your new API's query page.

1# Create a blog. Remember the returned id.
2# Provide the returned id as the "blogId" variable.
3mutation CreateBlog {
4  createBlog(input: {
5    name: "My New Blog!"
6  }) {
7    id
8    name
9  }
10}
11
12# Create a post and associate it with the blog via the "postBlogId" input field.
13# Provide the returned id as the "postId" variable.
14mutation CreatePost($blogId:ID!) {
15  createPost(input:{title:"My Post!", postBlogId: $blogId}) {
16    id
17    title
18    blog {
19      id
20      name
21    }
22  }
23}
24
25# Provide the returned id from the CreateBlog mutation as the "blogId" variable
26# in the "variables" pane (bottom left pane) of the query editor:
27{
28  "blogId": "returned-id-goes-here"
29}
30
31# Create a comment and associate it with the post via the "commentPostId" input field.
32mutation CreateComment($postId:ID!) {
33  createComment(input:{content:"A comment!", commentPostId:$postId}) {
34    id
35    content
36    post {
37      id
38      title
39      blog {
40        id
41        name
42      }
43    }
44  }
45}
46
47# Provide the returned id from the CreatePost mutation as the "postId" variable
48# in the "variables" pane (bottom left pane) of the query editor:
49{
50  "postId": "returned-id-goes-here"
51}
52
53# Get a blog, its posts, and its posts' comments.
54query GetBlog($blogId:ID!) {
55  getBlog(id:$blogId) {
56    id
57    name
58    posts(filter: {
59      title: {
60        eq: "My Post!"
61      }
62    }) {
63      items {
64        id
65        title
66        comments {
67          items {
68            id
69            content
70          }
71        }
72      }
73    }
74  }
75}
76
77# List all blogs, their posts, and their posts' comments.
78query ListBlogs {
79  listBlogs { # Try adding: listBlog(filter: { name: { eq: "My New Blog!" } })
80    items {
81      id
82      name
83      posts { # or try adding: posts(filter: { title: { eq: "My Post!" } })
84        items {
85          id
86          title
87          comments { # and so on ...
88            items {
89              id
90              content
91            }
92          }
93        }
94      }
95    }
96  }
97}

Update schema

If you want to update your API, open your project's backend/api/~apiname~/schema.graphql file (NOT the one in the backend/api/~apiname~/build folder) and edit it in your favorite code editor. You can compile the backend/api/~apiname~/schema.graphql by running:

1amplify api gql-compile

and view the compiled schema output in backend/api/~apiname~/build/schema.graphql.

You can then push updated changes with:

1amplify push

The following schema updates require replacement of the underlying DynamoDB table:

Removing or renaming a model
Modifying the primary key of a model
Modifying a Local Secondary Index of a model (only applies to projects with secondaryKeyAsGSI turned off)

When trying to push a schema change with one or more of these updates you will see an error message explaining that you will lose ALL DATA in any table that requires replacement. To confirm you want to continue with the deployment, run:

1amplify push --allow-destructive-graphql-schema-updates

In general, this command should only be used during development.

If you are making a breaking change to a production API but you want to retain the data in the affected table(s), you can create a backup before running amplify push --allow-destructive-graphql-schema-updates

Rebuild GraphQL API

Rebuild should NEVER be used in a production environment!

When in development, sometimes test data gets in a bad state or you want to make many changes to your schema all at once. In these cases, you may wish to "rebuild" all of the tables backing your schema. To do this, run:

1amplify rebuild api

This will recreate ALL of the tables backing models in your schema. ALL DATA in ALL TABLES will be deleted.

API Category Project Structure

At a high level, the transform libraries take a schema defined in the GraphQL Schema Definition Language (SDL) and converts it into a set of AWS CloudFormation templates and other assets that are deployed as part of amplify push. The full set of assets uploaded can be found at amplify/backend/api/YOUR-API-NAME/build.

When creating APIs, you will make changes to the other files and directories in the amplify/backend/api/YOUR-API-NAME/ directory but you should not manually change anything in the build directory. The build directory will be overwritten the next time you run amplify push or amplify api gql-compile. Here is an overview of the API directory:

1-build/
2- resolvers/
3| # Store any resolver templates written in vtl here. E.G.
4|-- Query.ping.req.vtl
5|-- Query.ping.res.vtl
6|
7- stacks/
8| # Create custom resources with CloudFormation stacks that will be deployed as part of `amplify push`.
9|-- CustomResources.json
10|
11- parameters.json
12| # Tweak certain behaviors with custom CloudFormation parameters.
13|
14- schema.graphql
15| # Write your GraphQL schema in SDL
16- schema/
17| # Optionally break up your schema into many files. You must remove schema.graphql to use this.
18|-- Query.graphql
19|-- Post.graphql
20- transform.conf.json