AWS AppSync
AWS AppSync Developer Guide

Resolver Mapping Template Reference for Lambda

The AWS AppSync Lambda resolver mapping templates enable you to shape requests from AWS AppSync to AWS Lambda functions located in your account, and responses from your Lambda functions back to AWS AppSync. Mapping templates also enable you to give hints to AWS AppSync about the nature of the operation to be invoked. This section describes the different mapping templates for the supported AWS Lambda operations.

Request Mapping Template

The Lambda request mapping template is fairly simple and allows as much context information as possible to pass to your Lambda function.

{ "version": string, "operation": Invoke|BatchInvoke, "payload": any type }

Here is the JSON schema representation of the Lambda request mapping template, once resolved.

{ "definitions": {}, "$schema": "http://json-schema.org/draft-06/schema#", "$id": "http://aws.amazon.com/appsync/request-mapping-template.json", "type": "object", "properties": { "version": { "$id": "/properties/version", "type": "string", "enum": [ "2017-02-28" ], "title": "The Mapping template version.", "default": "2017-02-28" }, "operation": { "$id": "/properties/operation", "type": "string", "enum": [ "Invoke", "BatchInvoke" ], "title": "The Mapping template operation.", "description": "What operation to execute.", "default": "Invoke" }, "payload": {} }, "required": [ "version", "operation" ], "additionalProperties": false }

Here is an example where we chose to pass the field value, and the GraphQL field arguments from the context.

{ "version": "2017-02-28", "operation": "Invoke", "payload": { "field": "getPost", "arguments": $utils.toJson($context.arguments) } }

The entire mapping document will be passed as input to your Lambda function, so that the previous example would now look like the following:

{ "version": "2017-02-28", "operation": "Invoke", "payload": { "field": "getPost", "arguments": { "id": "postId1" } } }

version

Common to all request mapping templates, version defines the version that the template uses. version is required.

"version": "2017-02-28"

operation

The Lambda data source allows you to define two operations, Invoke and BatchInvoke. The Invoke lets AWS AppSync know to call your Lambda function for every GraphQL field resolver, while BatchInvoke instructs AWS AppSync to batch requests for the current GraphQL field.

For Invoke, the resolved request mapping template exactly matches the input payload of the Lambda function. So the following sample template:

{ "version": "2017-02-28", "operation": "Invoke", "payload": { "arguments": $utils.toJson($context.arguments) } }

is resolved and passed to the Lambda function, as follows:

{ "version": "2017-02-28", "operation": "Invoke", "payload": { "arguments": { "id": "postId1" } } }

For BatchInvoke, the mapping template is applied for every field resolver in the batch. For conciseness, AWS AppSync merges all of the resolved mapping template payload values into a list under a single object matching the mapping template.

The following example template shows the merge:

{ "version": "2017-02-28", "operation": "BatchInvoke", "payload": $utils.toJson($context) }

This template is resolved into the following mapping document:

{ "version": "2017-02-28", "operation": "BatchInvoke", "payload": [ {...}, // context for batch item 1 {...}, // context for batch item 2 {...} // context for batch item 3 ] }

where each element of the payload list corresponds to a single batch item. The Lambda function is also expected to return a list-shaped response, matching the order of the items sent in the request, as follows:

[ { "data": {...}, "errorMessage": null, "errorType": null }, // result for batch item 1 { "data": {...}, "errorMessage": null, "errorType": null }, // result for batch item 2 { "data": {...}, "errorMessage": null, "errorType": null } // result for batch item 3 ]

operation is required.

payload

The payload field is a container that you can use to pass any well-formed JSON to the Lambda function.

If the operation field is set to BatchInvoke, AWS AppSync will wrap the existing payload values into a list.

payload is optional.

Response Mapping Template

As with other data sources, your Lambda function sends a response to AWS AppSync that needs to be converted to a GraphQL type.

The result of the Lambda function will be set on the context object that is available via the VTL $context.result property.

If the shape of your Lambda function response exactly matches the shape of the GraphQL type, you can forward the response using the following response mapping template:

$utils.toJson($context.result)

There are no required fields or shape restrictions that apply to the response mapping template. However, because GraphQL is strongly typed, the resolved mapping template must match the expected GraphQL type.

Lambda Function Batched Response

If the operation field is set to BatchInvoke, AWS AppSync expects a list of items back from the Lambda function. In order for AWS AppSync to map each result back to the original request item, the response list must match in size and order. It is ok to have null items in the response list; $ctx.result will be set to null accordingly.