JavaScript resolver function reference for Lambda

You can use the AWS AppSync function for AWS Lambda to shape requests from AWS AppSync to Lambda functions located in your account, and responses from your Lambda functions back to AWS AppSync. You can also specify the type of operation to perform in your request object. This section describes the requests for the supported Lambda operations.

Request object

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

type LambdaRequest = {
  operation: 'Invoke' | 'BatchInvoke';
  payload: any;
}; 

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

export function request(ctx) {
  return {
    operation: 'Invoke',
    payload: { field: 'getPost', arguments: ctx.args },
  };
}

The entire mapping document is 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"
        }
    }
}

Operation

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

operation is required.

For Invoke, the resolved request exactly matches the input payload of the Lambda function. So the following example request handler:

export function request(ctx) {
  return {
    operation: 'Invoke',
    payload: { field: 'getPost', arguments: ctx.args },
  };
}

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

{
    "version": "2018-05-29",
    "operation": "Invoke",
    "payload": {
        "arguments": {
            "id": "postId1"
        }
    }
}

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

The following example request handler shows the merge:

export function request(ctx) {
  return {
    operation: 'Invoke',
    payload: ctx,
  };
}

This request is evaluated and 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.

Payload

The payload field is a container that you can use to pass any data to the Lambda function.

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

payload is optional.

Response object

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

The result of the Lambda function is set on the context result property (context.result).

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

export function response(ctx) {
  return ctx.result
}

There are no required fields or shape restrictions that apply to the response object. However, because GraphQL is strongly typed, the resolved response 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 is set to null accordingly.