AWS Amplify announces the new GraphQL Transformer v2. More feature-rich, flexible, and extensible.

Today, AWS Amplify announces the GraphQL Transformer version 2, enabling developers to develop more feature-rich, flexible, and extensible GraphQL-based app backends even with minimal cloud expertise. The AWS Amplify CLI is a command line toolchain that helps frontend developers create app backends in the cloud. With the Transformer, developers can configure their backend data model using the GraphQL Schema Definition Language, and Amplify CLI automatically transforms the schema into a fully functioning GraphQL API with its underlying cloud infrastructure.

Install the latest version of Amplify CLI (npm i -g @aws-amplify/cli) and let’s review the top 5 new GraphQL features launching with GraphQL Transformer v2:

1. More explicit data modeling

With GraphQL Transformer v2, we made the modeling experience more explicit to give developers more control and easier understanding of their data model at a glance. Customers can still easily create a new DynamoDB table using the @model directive. With the new transformer, you gain new directives such as @primaryKey and @index to configure primary and secondary indexes.

In addition, to create relations between the data models, you can use @hasOne, @hasMany, @belongsTo, and @manyToMany directives.

Learn more about GraphQL Transformer v2’s Data Modeling.

2. Deny-by-default authorization

The new authorization rule system is now completely deny-by-default. Consistent for every authorization rule but don’t worry, we still provide a mechanism to configure a “global rule” to help you get started faster. With the new transformer, the authorization rules on your schema become the single source of truth for client-side data access. Also, there’s now an explicit rule hierarchy, meaning field-level rules overwrite model-level rules and model-level overwrite global rules.

Also, if you’re ever not sure about your model’s current access control matrix, you can run amplify status api -acm <YOUR_MODEL_NAME> to receive a print out on who can access what.

Learn more about GraphQL Transformer v2’s Authorization Rules.

3. Extending Amplify-generated pipeline resolvers

The new Transformer has been rewritten from the ground-up to use AWS AppSync pipeline resolvers. This means more modular and extensible resolver code for you! We now give you the ability to “slot in” your own custom business logic in between Amplify-generated resolvers or override Amplify-generated resolvers altogether. Simply place your custom VTL resolver with the correct naming convention into amplify/backend/api/<your-api-name>/resolvers/ folder, then upon the next amplify push, the Transformer incorporates the custom business logic into the deployed GraphQL API.

Learn more about how to Extend Amplify-generated Resolvers or Override Amplify-generated Resolvers.

4. Overriding the underlying GraphQL API cloud resources

Last week, we announced the ability to override Amplify-generated IAM, Cognito, and S3 configuration resources. This week, we’re announcing the ability to override Amplify-generated GraphQL API resources and REST API resources. Simply run amplify override api and then apply your infrastructure-level edits for any AppSync, DynamoDB, OpenSearch, and IAM resources generated by the GraphQL API.

amplify override api

For example, to enable X-Ray Tracing on the AppSync API, apply the following overrides:

import { AmplifyApiGraphQlResourceStackTemplate } from '@aws-amplify/cli-extensibility-helper';

export function override(resources: AmplifyApiGraphQlResourceStackTemplate) {
  resources.api.GraphQLAPI.xrayEnabled = true
}

Learn more about how to Override Amplify-generated GraphQL API resources.

5. Improved OpenSearch integration

The new GraphQL Transformer also provides more powerful OpenSearch queries. You can now run OpenSearch queries that are scoped to the current user’s access permissions. Run aggregation queries such as minimum value (min), maximum value (max), sum of values (sum), or average (avg). In addition, the new Transformer provides customers the ability to specify multiple sort conditions for the search results.

query MyQuery {
  searchStudents(
    aggregates: {
      type: min, # Specifies that you want the "min" value
      field: examsCompleted, # Specifies the field for the aggregate value
      name: "minimumExams" # provides a name to reference in the response field 
    } filter: { name: {wildcard: "Rene*"}}) {
    aggregateItems {
      name
      result {
        ... on SearchableAggregateScalarResult {
          value
        }
      }
    }
    total # Get total counts
  }
}

Learn more about GraphQL Transformer v2’s Search and Result Aggregations.

Migrate to the new GraphQL Transformer from version 1

If you’re an Amplify customer today using the GraphQL Transformer v1, make sure to review the GraphQL Transformer v1 to v2 Migration guide. We provide a migration helper that scans through your current GraphQL schema and helps migrate it to a v2-compatible schema.

Some v1 capabilities, such as using custom resolvers, overwritten resolvers, or using a relational data source, can’t be migrated using the amplify migrate api helper. Review Changes that Amplify CLI requires you to manually migrate to proceed further.

A new chapter for Amplify’s GraphQL support

These are just the top 5 features for GraphQL Transformer version 2. There is a whole range of additional features (such as Lambda authorizer support!) and DX enhancements (shorter “amplify add api” workflow!) that we couldn’t cover in this blog post. Review the new GraphQL documentation to dive deeper into all of the new features.

As always, feel free to reach out to the Amplify team via GitHub or join our Discord community.