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 Elasticsearch 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)