Configuring Resolvers

In this section, you walk through how to create a resolver, add a resolver for mutations, and use advanced configurations.

Create Your First Resolver

In the AWS AppSync console, go to the Schema page. In the Query type on the right side, choose Attach resolver next to the getTodos field. On the Create Resolver page, choose the data source you just created, and then choose a default template or paste in your own. For common use cases, the AWS AppSync console has built-in templates that you can use for getting items from data sources (for example, all item queries, individual lookups, etc.). For example, on the simple version of the schema from Designing Your Schema where getTodos didn’t have pagination, the mapping template is as follows:

{
    "version" : "2017-02-28",
    "operation" : "Scan"
}

You always need a response mapping template. The console provides a default with the following passthrough value for lists:

$util.toJson($context.result.items)

In this example, the context object (aliased as $ctx) for lists of items has the form $context.result.items. If your GraphQL operation returns a single item, it would be $context.result. AWS AppSync provides helper functions for common operations, such as the $util.toJson function listed previously, to format responses properly. For a full list of functions, see Resolver Mapping Template Utility Reference.

Note: The default resolver you have just created is a Unit resolver, but AppSync also supports creating Pipeline resolvers to run operations against multiple data sources in a sequence. See Pipeline Resolvers for more information.

Adding a Resolver for Mutations

Repeat the preceding process, starting at the Schema page and choosing Attach resolver for the addTodo mutation. Because this is a mutation where you’re adding a new item to DynamoDB, use the following request mapping template:

{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    },
    "attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}

AWS AppSync automatically converts arguments defined in the addTodo field from your GraphQL schema into DynamoDB operations. The previous example stores records in DynamoDB using a key of id, which is passed through from the mutation argument as $ctx.args.id. All of the other fields you pass through are automatically mapped to DynamoDB attributes with $util.dynamodb.toMapValuesJson($ctx.args).

For this resolver, use the following response mapping template:

$utils.toJson($context.result)

AWS AppSync also supports test and debug workflows for editing resolvers. You can use a mock context object to see the transformed value of the template before invoking. Optionally, you can view the full request execution to a data source interactively when you run a query. For more information, see Test and Debug Resolvers and Monitoring and Logging.

At this point, if you’re not using the advanced resolvers you can begin using your GraphQL API as outlined in Using Your API.

Advanced Resolvers

If you are following the Advanced section and you’re building a sample schema in Designing Your Schema to do a paginated scan, use the following request template for the getTodos field:

{
    "version" : "2017-02-28",
    "operation" : "Scan",
    "limit": $util.defaultIfNull(${ctx.args.limit}, 20),
    "nextToken": $util.toJson($util.defaultIfNullOrBlank($ctx.args.nextToken, null))
}

For this pagination use case, the response mapping is more than just a passthrough because it must contain both the cursor (so that the client knows what page to start at next) and the result set. The mapping template is as follows:

{
    "todos": $util.toJson($context.result.items),
    "nextToken": $util.toJson($context.result.nextToken)
}

The fields in the preceding response mapping template should match the fields defined in your TodoConnection type.

For the case of relations where you have a Comments table and you’re resolving the comments field on the Todo type (which returns a type of [Comment]), you can use a mapping template that runs a query against the second table. To do this, you must have already created a data source for the Comments table as outlined in Attaching a Data Source.

Note: We’re using a query operation against a second table for illustrative purposes only. You could use another operation against DynamoDB instead. Further, you could pull the data from another data source, such as AWS Lambda or Amazon OpenSearch Service, because the relation is controlled by your GraphQL schema.

On the Schema page in the console, choose the comments field in Todo type, and then choose Attach. Choose Comments table data source and use the following request mapping template:

{
    "version": "2017-02-28",
    "operation": "Query",
    "index": "todoid-index",
    "query": {
        "expression": "todoid = :todoid",
        "expressionValues": {
            ":todoid": {
                "S": $util.toJson($context.source.id)
            }
        }
    }
}

The context.source references the parent object of the current field that’s being resolved. In this example, source.id refers to the individual Todo object, which is then used for the query expression.

You can use the passthrough response mapping template as follows:

$util.toJson($ctx.result.items)

Finally, on the Schema page in the console, attach a resolver to the addComment field, and specify the data source for the Comments table. The request mapping template in this case is a simple PutItem with the specific todoid that is commented on as an argument, but you use the $utils.autoId() utility to create a unique sort key for the comment as follows:

{
    "version": "2017-02-28",
    "operation": "PutItem",
    "key": {
        "todoid": { "S": $util.toJson($context.arguments.todoid) },
        "commentid": { "S": "$util.autoId()" }
    },
    "attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}

Use a passthrough response template as follows:

$util.toJson($ctx.result)