export const meta = { title: `Overview`, description: `With Amplify CLI and GraphQL Transform, you define your application's data model using the GraphQL Schema Definition Language (SDL) and the library converts your SDL schema into a set of fully descriptive AWS CloudFormation templates that implement your data model.`, }; 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: ```graphql type Blog @model { id: ID! name: String! posts: [Post] @connection(name: "BlogPosts") } type Post @model { id: ID! title: String! blog: Blog @connection(name: "BlogPosts") comments: [Comment] @connection(name: "PostComments") } type Comment @model { id: ID! content: String post: Post @connection(name: "PostComments") } ``` 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)](https://graphql.org/learn/schema/) 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: ```bash amplify init ``` Follow the wizard to create a new app. After finishing the wizard run: ```bash amplify 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. ```graphql type Blog @model { id: ID! name: String! posts: [Post] @connection(name: "BlogPosts") } type Post @model { id: ID! title: String! blog: Blog @connection(name: "BlogPosts") comments: [Comment] @connection(name: "PostComments") } type Comment @model { id: ID! content: String post: Post @connection(name: "PostComments") } ``` 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. ```bash amplify 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. ```graphql # Create a blog. Remember the returned id. # Provide the returned id as the "blogId" variable. mutation CreateBlog { createBlog(input: { name: "My New Blog!" }) { id name } } # Create a post and associate it with the blog via the "postBlogId" input field. # Provide the returned id as the "postId" variable. mutation CreatePost($blogId:ID!) { createPost(input:{title:"My Post!", postBlogId: $blogId}) { id title blog { id name } } } # Provide the returned id from the CreateBlog mutation as the "blogId" variable # in the "variables" pane (bottom left pane) of the query editor: { "blogId": "returned-id-goes-here" } # Create a comment and associate it with the post via the "commentPostId" input field. mutation CreateComment($postId:ID!) { createComment(input:{content:"A comment!", commentPostId:$postId}) { id content post { id title blog { id name } } } } # Provide the returned id from the CreatePost mutation as the "postId" variable # in the "variables" pane (bottom left pane) of the query editor: { "postId": "returned-id-goes-here" } # Get a blog, its posts, and its posts' comments. query GetBlog($blogId:ID!) { getBlog(id:$blogId) { id name posts(filter: { title: { eq: "My Post!" } }) { items { id title comments { items { id content } } } } } } # List all blogs, their posts, and their posts' comments. query ListBlogs { listBlogs { # Try adding: listBlog(filter: { name: { eq: "My New Blog!" } }) items { id name posts { # or try adding: posts(filter: { title: { eq: "My Post!" } }) items { id title comments { # and so on ... items { id content } } } } } } } ``` ## 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: ```bash amplify api gql-compile ``` and view the compiled schema output in `backend/api/~apiname~/build/schema.graphql`. You can then push updated changes with: ```bash amplify push ``` The following schema updates require replacement of the underlying DynamoDB table: 1. Removing or renaming a model 2. Modifying the [primary key](/cli/graphql-transformer/key) of a model 3. Modifying a Local Secondary Index of a model (only applies to projects with [secondaryKeyAsGSI](/cli/reference/feature-flags/#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: ```bash amplify 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](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/CreateBackupAWS.html) 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: ```bash amplify 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: ```console -build/ - resolvers/ | # Store any resolver templates written in vtl here. E.G. |-- Query.ping.req.vtl |-- Query.ping.res.vtl | - stacks/ | # Create custom resources with CloudFormation stacks that will be deployed as part of `amplify push`. |-- CustomResources.json | - parameters.json | # Tweak certain behaviors with custom CloudFormation parameters. | - schema.graphql | # Write your GraphQL schema in SDL - schema/ | # Optionally break up your schema into many files. You must remove schema.graphql to use this. |-- Query.graphql |-- Post.graphql - transform.conf.json ```