Resolver mapping template reference for Lambda - AWS AppSync

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": "", "$id": "", "type": "object", "properties": { "version": { "$id": "/properties/version", "type": "string", "enum": [ "2018-05-29" ], "title": "The Mapping template version.", "default": "2018-05-29" }, "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": "2018-05-29", "operation": "Invoke", "payload": { "field": "getPost", "arguments": $util.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": "2018-05-29", "operation": "Invoke", "payload": { "field": "getPost", "arguments": { "id": "postId1" } } }


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

"version": "2018-05-29"


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.

operation is required.

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

{ "version": "2018-05-29", "operation": "Invoke", "payload": { "arguments": $util.toJson($context.arguments) } }

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

{ "version": "2018-05-29", "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": "2018-05-29", "operation": "BatchInvoke", "payload": $util.toJson($context) }

This template is resolved into the following mapping document:

{ "version": "2018-05-29", "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.


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:


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.

Direct Lambda resolvers

If you wish to circumvent the use of mapping templates entirely, AWS AppSync can provide a default payload to your Lamdba function and a default of a Lambda function's response to a GraphQL type. You can choose to provide a request template, a response template, or neither and AWS AppSync handles it accordingly.

Direct Lambda request mapping template

When the request mapping template is not provided, AWS AppSync will send the Context object directly to your Lambda function as an Invoke operation. For more information about the structure of the Context object, see Context.

Direct Lambda response mapping template

When the response mapping template is not provided, AWS AppSync will do one of two things upon receiving your Lambda function's response. If you did not provide a request mapping template, or if you provided a request mapping template with the version "2018-05-29", the response logic functions equivalent to the following response mapping template:

#if($ctx.error) $util.error($ctx.error.message, $ctx.error.type, $ctx.result) #end $util.toJson($ctx.result)

If you provided a template with the version "2017-02-28", the response logic functions equivalent to the following response mapping template:


Superficially, the mapping template bypass operates similarly to using certain mapping templates, as shown in the preceding examples. However, behind the scenes, the evaluation of the mapping templates are circumvented entirely. Because the template evaluation step is bypassed, in some scenarios applications might experience less overhead and latency during the response when compared to a Lambda function with a response mapping template that needs to be evaluated.

Custom error handling in Direct Lambda resolver responses

You can customize error responses from Lambda functions that are invoked by Direct Lambda resolvers by raising a custom exception. The following example demonstrates how to create a custom exception using JavaScript.

class CustomException extends Error { constructor(message) { super(message); = "CustomException"; } } throw new CustomException("Custom message");

When exceptions are raised, the errorType and errorMessage will be the name and message, respectively, of the custom error that is thrown.

If errorType is UnauthorizedException, AWS AppSync returns the default message ("You are not authorized to make this call.") instead of a custom message.

The following is an example GraphQL response that demonstrates a custom errorType.

{ "data": { "query": null }, "errors": [ { "path": [ "query" ], "data": null, "errorType": "CustomException", "errorInfo": null, "locations": [ { "line": 5, "column": 10, "sourceName": null } ], "message": "Custom Message" } ] }