Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

JavaScript resolver function reference for DynamoDB

The Amazon AppSync DynamoDB function enables you to use GraphQL to store and retrieve data in existing Amazon DynamoDB tables in your account. This resolver works by enabling you to map an incoming GraphQL request into a DynamoDB call, and then map the DynamoDB response back to GraphQL. This section describes the request and response handlers for supported DynamoDB operations.

GetItem

The GetItem request lets you tell the Amazon AppSync DynamoDB function to make a GetItem request to DynamoDB, and enables you to specify:

The GetItem request has the following structure:

type DynamoDBGetItem = {
  operation: 'GetItem';
  key: { [key: string]: any };
  consistentRead?: ConsistentRead;
  projection?: {
    expression: string;
    expressionNames?: { [key: string]: string };
  };
};

The fields are defined as follows:

GetItem fields

The item returned from DynamoDB is automatically converted into GraphQL and JSON primitive types, and is available in the context result (context.result).

For more information about DynamoDB type conversion, see Type system (response mapping).

For more information about JavaScript resolvers, see JavaScript resolvers overview.

Example

The following example is a function request handler for a GraphQL query getThing(foo: String!, bar: String!):

export function request(ctx) {
  const {foo, bar} = ctx.args
  return {
    operation : "GetItem",
    key : util.dynamodb.toMapValues({foo, bar}),
    consistentRead : true
  }
}

For more information about the DynamoDB GetItem API, see the DynamoDB API documentation.

PutItem

The PutItem request mapping document lets you tell the Amazon AppSync DynamoDB function to make a PutItem request to DynamoDB, and enables you to specify the following:

The PutItem request has the following structure:

type DynamoDBPutItemRequest = {
  operation: 'PutItem';
  key: { [key: string]: any };
  attributeValues: { [key: string]: any};
  condition?: ConditionCheckExpression;
  customPartitionKey?: string;
  populateIndexFields?: boolean;
  _version?: number;
};

The fields are defined as follows:

PutItem fields

The item written to DynamoDB is automatically converted into GraphQL and JSON primitive types and is available in the context result (context.result).

For more information about DynamoDB type conversion, see Type system (response mapping).

For more information about JavaScript resolvers, see JavaScript resolvers overview.

Example 1

The following example is a function request handler for a GraphQL mutation updateThing(foo: String!, bar: String!, name: String!, version: Int!).

If no item with the specified key exists, it’s created. If an item already exists with the specified key, it’s overwritten.

import { util } from '@aws-appsync/utils';
export function request(ctx) {
  const { foo, bar, ...values} = ctx.args
  return {
    operation: 'PutItem',
    key: util.dynamodb.toMapValues({foo, bar}),
    attributeValues: util.dynamodb.toMapValues(values),
  };
}

Example 2

The following example is a function request handler for a GraphQL mutation updateThing(foo: String!, bar: String!, name: String!, expectedVersion: Int!).

This example verifies that the item currently in DynamoDB has the version field set to expectedVersion.

import { util } from '@aws-appsync/utils';
export function request(ctx) {
  const { foo, bar, name, expectedVersion } = ctx.args;
  const values = { name, version: expectedVersion + 1 };
  let condition = util.transform.toDynamoDBConditionExpression({
    version: { eq: expectedVersion },
  });

  return {
    operation: 'PutItem',
    key: util.dynamodb.toMapValues({ foo, bar }),
    attributeValues: util.dynamodb.toMapValues(values),
    condition,
  };
}

For more information about the DynamoDB PutItem API, see the DynamoDB API documentation.

UpdateItem

The UpdateItem request enables you to tell the Amazon AppSync DynamoDB function to make a UpdateItem request to DynamoDB and allows you to specify the following:

The UpdateItem request has the following structure:

type DynamoDBUpdateItemRequest = {
  operation: 'UpdateItem';
  key: { [key: string]: any };
  update: {
    expression: string;
    expressionNames?: { [key: string]: string };
    expressionValues?: { [key: string]: any };
  };
  condition?: ConditionCheckExpression;
  customPartitionKey?: string;
  populateIndexFields?: boolean;
  _version?: number;
};

The fields are defined as follows:

UpdateItem fields

The item updated in DynamoDB is automatically converted into GraphQL and JSON primitive types and is available in the context result (context.result).

For more information about DynamoDB type conversion, see Type system (response mapping).

For more information about JavaScript resolvers, see JavaScript resolvers overview.

Example 1

The following example is a function request handler for the GraphQL mutation upvote(id: ID!).

In this example, an item in DynamoDB has its upvotes and version fields incremented by 1.

import { util } from '@aws-appsync/utils';
export function request(ctx) {
  const { id } = ctx.args;
  return {
    operation: 'UpdateItem',
    key: util.dynamodb.toMapValues({ id }),
    update: {
      expression: 'ADD #votefield :plusOne, version :plusOne',
      expressionNames: { '#votefield': 'upvotes' },
      expressionValues: { ':plusOne': { N: 1 } },
    },
  };
}

Example 2

The following example is a function request handler for a GraphQL mutation updateItem(id: ID!, title: String, author: String, expectedVersion: Int!).

This is a complex example that inspects the arguments and dynamically generates the update expression that only includes the arguments that have been provided by the client. For example, if title and author are omitted, they are not updated. If an argument is specified but its value is null, then that field is deleted from the object in DynamoDB. Finally, the operation has a condition, which verifies whether the item currently in DynamoDB has the version field set to expectedVersion:

import { util } from '@aws-appsync/utils';
export function request(ctx) {
  const { args: { input: { id, ...values } } } = ctx;

  const condition = {
    id: { attributeExists: true },
    version: { eq: values.expectedVersion },
  };
  values.expectedVersion += 1;
  return dynamodbUpdateRequest({ keys: { id }, values, condition });
}


/**
 * Helper function to update an item
 * @returns an UpdateItem request
 */
function dynamodbUpdateRequest(params) {
  const { keys, values, condition: inCondObj } = params;

  const sets = [];
  const removes = [];
  const expressionNames = {};
  const expValues = {};

  // Iterate through the keys of the values
  for (const [key, value] of Object.entries(values)) {
    expressionNames[`#${key}`] = key;
    if (value) {
      sets.push(`#${key} = :${key}`);
      expValues[`:${key}`] = value;
    } else {
      removes.push(`#${key}`);
    }
  }

  let expression = sets.length ? `SET ${sets.join(', ')}` : '';
  expression += removes.length ? ` REMOVE ${removes.join(', ')}` : '';

  const condition = JSON.parse(
    util.transform.toDynamoDBConditionExpression(inCondObj)
  );

  return {
    operation: 'UpdateItem',
    key: util.dynamodb.toMapValues(keys),
    condition,
    update: {
      expression,
      expressionNames,
      expressionValues: util.dynamodb.toMapValues(expValues),
    },
  };
}

For more information about the DynamoDB UpdateItem API, see the DynamoDB API documentation.

DeleteItem

The DeleteItem request lets you tell the Amazon AppSync DynamoDB function to make a DeleteItem request to DynamoDB, and enables you to specify the following:

The DeleteItem request has the following structure:

type DynamoDBDeleteItemRequest = {
  operation: 'DeleteItem';
  key: { [key: string]: any };
  condition?: ConditionCheckExpression;
  customPartitionKey?: string;
  populateIndexFields?: boolean;
  _version?: number;
};

The fields are defined as follows:

DeleteItem fields

The item deleted from DynamoDB is automatically converted into GraphQL and JSON primitive types and is available in the context result (context.result).

For more information about DynamoDB type conversion, see Type system (response mapping).

For more information about JavaScript resolvers, see JavaScript resolvers overview.

Example 1

The following example is a function request handler for a GraphQL mutation deleteItem(id: ID!). If an item exists with this ID, it’s deleted.

import { util } from '@aws-appsync/utils';
export function request(ctx) {
  return {
    operation: 'DeleteItem',
    key: util.dynamodb.toMapValues({ id: ctx.args.id }),
  };
}

Example 2

The following example is a function request handler for a GraphQL mutation deleteItem(id: ID!, expectedVersion: Int!). If an item exists with this ID, it’s deleted, but only if its version field set to expectedVersion:

import { util } from '@aws-appsync/utils';

export function request(ctx) {
  const { id, expectedVersion } = ctx.args;
  const condition = {
    id: { attributeExists: true },
    version: { eq: expectedVersion },
  };
  return {
    operation: 'DeleteItem',
    key: util.dynamodb.toMapValues({ id }),
    condition: util.transform.toDynamoDBConditionExpression(condition),
  };
}

For more information about the DynamoDB DeleteItem API, see the DynamoDB API documentation.

Query

The Query request object lets you tell the Amazon AppSync DynamoDB resolver to make a Query request to DynamoDB, and enables you to specify the following:

The Query request object has the following structure:

type DynamoDBQueryRequest = {
  operation: 'Query';
  query: {
    expression: string;
    expressionNames?: { [key: string]: string };
    expressionValues?: { [key: string]: any };
  };
  index?: string;
  nextToken?: string;
  limit?: number;
  scanIndexForward?: boolean;
  consistentRead?: boolean;
  select?: 'ALL_ATTRIBUTES' | 'ALL_PROJECTED_ATTRIBUTES' | 'SPECIFIC_ATTRIBUTES';
  filter?: {
    expression: string;
    expressionNames?: { [key: string]: string };
    expressionValues?: { [key: string]: any };
  };
  projection?: {
    expression: string;
    expressionNames?: { [key: string]: string };
  };
};

The fields are defined as follows:

Query fields

The results from DynamoDB are automatically converted into GraphQL and JSON primitive types and are available in the context result (context.result).

For more information about DynamoDB type conversion, see Type system (response mapping).

For more information about JavaScript resolvers, see JavaScript resolvers overview.

The results have the following structure:

{
    items = [ ... ],
    nextToken = "a pagination token",
    scannedCount = 10
}

The fields are defined as follows:

Example

The following example is a function request handler for a GraphQL query getPosts(owner: ID!).

In this example, a global secondary index on a table is queried to return all posts owned by the specified ID.

import { util } from '@aws-appsync/utils';

export function request(ctx) {
  const { owner } = ctx.args;
  return {
    operation: 'Query',
    query: {
      expression: 'ownerId = :ownerId',
      expressionValues: util.dynamodb.toMapValues({ ':ownerId': owner }),
    },
    index: 'owner-index',
  };
}

For more information about the DynamoDB Query API, see the DynamoDB API documentation.

Scan

The Scan request lets you tell the Amazon AppSync DynamoDB function to make a Scan request to DynamoDB, and enables you to specify the following:

The Scan request object has the following structure:

type DynamoDBScanRequest = {
  operation: 'Scan';
  index?: string;
  limit?: number;
  consistentRead?: boolean;
  nextToken?: string;
  totalSegments?: number;
  segment?: number;
  filter?: {
    expression: string;
    expressionNames?: { [key: string]: string };
    expressionValues?: { [key: string]: any };
  };
  projection?: {
    expression: string;
    expressionNames?: { [key: string]: string };
  };
};

The fields are defined as follows:

Scan fields

The results returned by the DynamoDB scan are automatically converted into GraphQL and JSON primitive types and is available in the context result (context.result).

For more information about DynamoDB type conversion, see Type system (response mapping).

For more information about JavaScript resolvers, see JavaScript resolvers overview.

The results have the following structure:

{
    items = [ ... ],
    nextToken = "a pagination token",
    scannedCount = 10
}

The fields are defined as follows:

Example 1

The following example is a function request handler for the GraphQL query: allPosts.

In this example, all entries in the table are returned.

export function request(ctx) {
  return { operation: 'Scan' };
}

Example 2

The following example is a function request handler for the GraphQL query: postsMatching(title: String!).

In this example, all entries in the table are returned where the title starts with the title argument.

export function request(ctx) {
  const { title } = ctx.args;
  const filter = { filter: { beginsWith: title } };
  return {
    operation: 'Scan',
    filter: JSON.parse(util.transform.toDynamoDBFilterExpression(filter)),
  };
}

For more information about the DynamoDB Scan API, see the DynamoDB API documentation.

Sync

The Sync request object lets you retrieve all the results from a DynamoDB table and then receive only the data altered since your last query (the delta updates). Sync requests can only be made to versioned DynamoDB data sources. You can specify the following:

The Sync request object has the following structure:

type DynamoDBSyncRequest = {
  operation: 'Sync';
  basePartitionKey?: string;
  deltaIndexName?: string;
  limit?: number;
  nextToken?: string;
  lastSync?: number;
  filter?: {
    expression: string;
    expressionNames?: { [key: string]: string };
    expressionValues?: { [key: string]: any };
  };
};

The fields are defined as follows:

Sync fields

The results returned by the DynamoDB sync are automatically converted into GraphQL and JSON primitive types and are available in the context result (context.result).

For more information about DynamoDB type conversion, see Type system (response mapping).

For more information about JavaScript resolvers, see JavaScript resolvers overview.

The results have the following structure:

{
    items = [ ... ],
    nextToken = "a pagination token",
    scannedCount = 10,
    startedAt = 1550000000000
}

The fields are defined as follows:

Example 1

The following example is a function request handler for the GraphQL query: syncPosts(nextToken: String, lastSync: AWSTimestamp).

In this example, if lastSync is omitted, all entries in the base table are returned. If lastSync is supplied, only the entries in the delta sync table that have changed since lastSync are returned.

export function request(ctx) {
  const { nextToken, lastSync } = ctx.args;
  return { operation: 'Sync', limit: 100, nextToken, lastSync };
}

BatchGetItem

The BatchGetItem request object lets you tell the Amazon AppSync DynamoDB function to make a BatchGetItem request to DynamoDB to retrieve multiple items, potentially across multiple tables. For this request object, you must specify the following:

The DynamoDB BatchGetItem limits apply and no condition expression can be provided.

The BatchGetItem request object has the following structure:

type DynamoDBBatchGetItemRequest = {
  operation: 'BatchGetItem';
  tables: {
    [tableName: string]: {
      keys: { [key: string]: any }[];
      consistentRead?: boolean; 
      projection?: {
        expression: string;
        expressionNames?: { [key: string]: string };
      };
    };
  };
};

The fields are defined as follows:

BatchGetItem fields

Things to remember:

For the following example function request handler:

import { util } from '@aws-appsync/utils';

export function request(ctx) {
  const { authorId, postId } = ctx.args;
  return {
    operation: 'BatchGetItem',
    tables: {
      authors: [util.dynamodb.toMapValues({ authorId })],
      posts: [util.dynamodb.toMapValues({ authorId, postId })],
    },
  };
}

The invocation result available in ctx.result is as follows:

{
   "data": {
     "authors": [null],
     "posts": [
        // Was retrieved
        {
          "authorId": "a1",
          "postId": "p2",
          "postTitle": "title",
          "postDescription": "description",
        }
     ]
   },
   "unprocessedKeys": {
     "authors": [
        // This item was not processed due to an error
        {
          "authorId": "a1"
        }
      ],
     "posts": []
   }
}

The ctx.error contains details about the error. The keys data, unprocessedKeys, and each table key that was provided in the result in the function request object are guaranteed to be present in the invocation result. Items that have been deleted appear in the data block. Items that haven’t been processed are marked as null inside the data block and are placed inside the unprocessedKeys block.

BatchDeleteItem

The BatchDeleteItem request object lets you tell the Amazon AppSync DynamoDB function to make a BatchWriteItem request to DynamoDB to delete multiple items, potentially across multiple tables. For this request object, you must specify the following:

The DynamoDB BatchWriteItem limits apply and no condition expression can be provided.

The BatchDeleteItem request object has the following structure:

type DynamoDBBatchDeleteItemRequest = {
  operation: 'BatchDeleteItem';
  tables: {
    [tableName: string]: { [key: string]: any }[];
  };
};

The fields are defined as follows:

BatchDeleteItem fields

Things to remember:

For the following example function request handler:

import { util } from '@aws-appsync/utils';

export function request(ctx) {
  const { authorId, postId } = ctx.args;
  return {
    operation: 'BatchDeleteItem',
    tables: {
      authors: [util.dynamodb.toMapValues({ authorId })],
      posts: [util.dynamodb.toMapValues({ authorId, postId })],
    },
  };
}

The invocation result available in ctx.result is as follows:

{
   "data": {
     "authors": [null],
     "posts": [
        // Was deleted
        {
          "authorId": "a1",
          "postId": "p2"
        }
     ]
   },
   "unprocessedKeys": {
     "authors": [
        // This key was not processed due to an error
        {
          "authorId": "a1"
        }
      ],
     "posts": []
   }
}

The ctx.error contains details about the error. The keys data, unprocessedKeys, and each table key that was provided in the function request object are guaranteed to be present in the invocation result. Items that have been deleted are present in the data block. Items that haven’t been processed are marked as null inside the data block and are placed inside the unprocessedKeys block.

BatchPutItem

The BatchPutItem request object lets you tell the Amazon AppSync DynamoDB function to make a BatchWriteItem request to DynamoDB to put multiple items, potentially across multiple tables. For this request object, you must specify the following:

The DynamoDB BatchWriteItem limits apply and no condition expression can be provided.

The BatchPutItem request object has the following structure:

type DynamoDBBatchPutItemRequest = {
  operation: 'BatchPutItem';
  tables: {
    [tableName: string]: { [key: string]: any}[];
  };
};

The fields are defined as follows:

BatchPutItem fields

Things to remember:

For the following example function request handler:

import { util } from '@aws-appsync/utils';

export function request(ctx) {
  const { authorId, postId, name, title } = ctx.args;
  return {
    operation: 'BatchPutItem',
    tables: {
      authors: [util.dynamodb.toMapValues({ authorId, name })],
      posts: [util.dynamodb.toMapValues({ authorId, postId, title })],
    },
  };
}

The invocation result available in ctx.result is as follows:

{
   "data": {
     "authors": [
         null
     ],
     "posts": [
        // Was inserted
        {
          "authorId": "a1",
          "postId": "p2",
          "title": "title"
        }
     ]
   },
   "unprocessedItems": {
     "authors": [
        // This item was not processed due to an error
        {
          "authorId": "a1",
          "name": "a1_name"
        }
      ],
     "posts": []
   }
}

The ctx.error contains details about the error. The keys data, unprocessedItems, and each table key that was provided in the request object are guaranteed to be present in the invocation result. Items that have been inserted are in the data block. Items that haven’t been processed are marked as null inside the data block and are placed inside the unprocessedItems block.

TransactGetItems

The TransactGetItems request object lets you to tell the Amazon AppSync DynamoDB function to make a TransactGetItems request to DynamoDB to retrieve multiple items, potentially across multiple tables. For this request object, you must specify the following:

The DynamoDB TransactGetItems limits apply and no condition expression can be provided.

The TransactGetItems request object has the following structure:

type DynamoDBTransactGetItemsRequest = {
  operation: 'TransactGetItems';
  transactItems: { table: string; key: { [key: string]: any }; projection?: { expression: string; expressionNames?: { [key: string]: string }; }[];
  };
};

The fields are defined as follows:

TransactGetItems fields

Things to remember:

For the following example function request handler:

import { util } from '@aws-appsync/utils';

export function request(ctx) {
  const { authorId, postId } = ctx.args;
  return {
    operation: 'TransactGetItems',
    transactItems: [
      {
        table: 'posts',
        key: util.dynamodb.toMapValues({ postId }),
      },
      {
        table: 'authors',
        key: util.dynamodb.toMapValues({ authorId }),
      },
    ],
  };
}

If the transaction succeeds and only the first requested item is retrieved, the invocation result available in ctx.result is as follows:

{
    "items": [
       {
           // Attributes of the first requested item
           "post_id": "p1",
           "post_title": "title",
           "post_description": "description"
       },
       // Could not retrieve the second requested item
       null,
    ],
    "cancellationReasons": null
}

If the transaction fails due to TransactionCanceledException caused by the first request item, the invocation result available in ctx.result is as follows:

{
    "items": null,
    "cancellationReasons": [
       {
           "type":"Sample error type",
           "message":"Sample error message"
       },
       {
           "type":"None",
           "message":"None"
       }
    ]
}

The ctx.error contains details about the error. The keys items and cancellationReasons are guaranteed to be present in ctx.result.

TransactWriteItems

The TransactWriteItems request object lets you tell the Amazon AppSync DynamoDB function to make a TransactWriteItems request to DynamoDB to write multiple items, potentially to multiple tables. For this request object, you must specify the following:

The DynamoDB TransactWriteItems limits apply.

The TransactWriteItems request object has the following structure:

type DynamoDBTransactWriteItemsRequest = {
  operation: 'TransactWriteItems';
  transactItems: TransactItem[];
};
type TransactItem =
  | TransactWritePutItem
  | TransactWriteUpdateItem
  | TransactWriteDeleteItem
  | TransactWriteConditionCheckItem;
type TransactWritePutItem = {
  table: string;
  operation: 'PutItem';
  key: { [key: string]: any };
  attributeValues: { [key: string]: string};
  condition?: TransactConditionCheckExpression;
};
type TransactWriteUpdateItem = {
  table: string;
  operation: 'UpdateItem';
  key: { [key: string]: any };
  update: DynamoDBExpression;
  condition?: TransactConditionCheckExpression;
};
type TransactWriteDeleteItem = {
  table: string;
  operation: 'DeleteItem';
  key: { [key: string]: any };
  condition?: TransactConditionCheckExpression;
};
type TransactWriteConditionCheckItem = {
  table: string;
  operation: 'ConditionCheck';
  key: { [key: string]: any };
  condition?: TransactConditionCheckExpression;
};
type TransactConditionCheckExpression = {
  expression: string;
  expressionNames?: { [key: string]: string};
  expressionValues?: { [key: string]: any};
  returnValuesOnConditionCheckFailure: boolean;
};

TransactWriteItems fields

Things to remember:

For the following example function request handler:

import { util } from '@aws-appsync/utils';

export function request(ctx) {
  const { authorId, postId, title, description, oldTitle, authorName } = ctx.args;
  return {
    operation: 'TransactWriteItems',
    transactItems: [
      {
        table: 'posts',
        operation: 'PutItem',
        key: util.dynamodb.toMapValues({ postId }),
        attributeValues: util.dynamodb.toMapValues({ title, description }),
        condition: util.transform.toDynamoDBConditionExpression({
          title: { eq: oldTitle },
        }),
      },
      {
        table: 'authors',
        operation: 'UpdateItem',
        key: util.dynamodb.toMapValues({ authorId }),
        update: {
          expression: 'SET authorName = :name',
          expressionValues: util.dynamodb.toMapValues({ ':name': authorName }),
        },
      },
    ],
  };
}

If the transaction succeeds, the invocation result available in ctx.result is as follows:

{
    "keys": [
       // Key of the PutItem request
       {
           "post_id": "p1",
       },
       // Key of the UpdateItem request
       {
           "author_id": "a1"
       }
    ],
    "cancellationReasons": null
}

If the transaction fails due to condition check failure of the PutItem request, the invocation result available in ctx.result is as follows:

{
    "keys": null,
    "cancellationReasons": [
       {
           "item": {
               "post_id": "p1",
               "post_title": "Actual old title",
               "post_description": "Old description"
           },
           "type": "ConditionCheckFailed",
           "message": "The condition check failed."
       },
       {
           "type": "None",
           "message": "None"
       }
    ]
}

The ctx.error contains details about the error. The keys keys and cancellationReasons are guaranteed to be present in ctx.result.

Type system (request mapping)

When using the Amazon AppSync DynamoDB function to call your DynamoDB tables, Amazon AppSync needs to know the type of each value to use in that call. This is because DynamoDB supports more type primitives than GraphQL or JSON (such as sets and binary data). Amazon AppSync needs some hints when translating between GraphQL and DynamoDB, otherwise it would have to make some assumptions on how data is structured in your table.

For more information about DynamoDB data types, see the DynamoDB Data type descriptors and Data types documentation.

A DynamoDB value is represented by a JSON object containing a single key-value pair. The key specifies the DynamoDB type, and the value specifies the value itself. In the following example, the key S denotes that the value is a string, and the value identifier is the string value itself.

{ "S" : "identifier" }

Note that the JSON object cannot have more than one key-value pair. If more than one key-value pair is specified, the request object isn’t parsed.

A DynamoDB value is used anywhere in a request object where you need to specify a value. Some places where you need to do this include: key and attributeValue sections, and the expressionValues section of expression sections. In the following example, the DynamoDB String value identifier is being assigned to the id field in a key section (perhaps in a GetItem request object).

"key" : {
   "id" : { "S" : "identifier" }
}

Supported Types

Amazon AppSync supports the following DynamoDB scalar, document, and set types:

For more information about each type, see the DynamoDB documentation .

Type system (response mapping)

When receiving a response from DynamoDB, Amazon AppSync automatically converts it into GraphQL and JSON primitive types. Each attribute in DynamoDB is decoded and returned in the response handler's context.

For example, if DynamoDB returns the following:

{
    "id" : { "S" : "1234" },
    "name" : { "S" : "Nadia" },
    "age" : { "N" : 25 }
}

When the result is returned from your pipeline resolver, Amazon AppSync converts it into GraphQL and JSON types as:

{
    "id" : "1234",
    "name" : "Nadia",
    "age" : 25
}

This section explains how Amazon AppSync converts the following DynamoDB scalar, document, and set types:

Filters

When querying objects in DynamoDB using the Query and Scan operations, you can optionally specify a filter that evaluates the results and returns only the desired values.

The filter property of a Query or Scan request has the following structure:

type DynamoDBExpression = {
  expression: string;
  expressionNames?: { [key: string]: string};
  expressionValues?: { [key: string]: any};
};

The fields are defined as follows:

Example

The following example is a filter section for a request, where entries retrieved from DynamoDB are only returned if the title starts with the title argument.

Here we use the util.transform.toDynamoDBFilterExpression to automatically create a filter from an object:

const filter = util.transform.toDynamoDBFilterExpression({
  title: { beginsWith: 'far away' },
});

const request = {};
request.filter = JSON.parse(filter);

This generates the following filter:

{
  "filter": {
    "expression": "(begins_with(#title,:title_beginsWith))",
    "expressionNames": { "#title": "title" },
    "expressionValues": {
      ":title_beginsWith": { "S": "far away" }
    }
  }
}

Condition expressions

When you mutate objects in DynamoDB by using the PutItem, UpdateItem, and DeleteItem DynamoDB operations, you can optionally specify a condition expression that controls whether the request should succeed or not, based on the state of the object already in DynamoDB before the operation is performed.

The Amazon AppSync DynamoDB function allows a condition expression to be specified in PutItem, UpdateItem, and DeleteItem request objects, and also a strategy to follow if the condition fails and the object was not updated.

Example 1

The following PutItem request object doesn’t have a condition expression. As a result, it puts an item in DynamoDB even if an item with the same key already exists, thereby overwriting the existing item.

import { util } from '@aws-appsync/utils';
export function request(ctx) {
  const { foo, bar, ...values} = ctx.args
  return {
    operation: 'PutItem',
    key: util.dynamodb.toMapValues({foo, bar}),
    attributeValues: util.dynamodb.toMapValues(values),
  };
}

Example 2

The following PutItem object does have a condition expression that allows the operation succeed only if an item with the same key does not exist in DynamoDB.

import { util } from '@aws-appsync/utils';
export function request(ctx) {
  const { foo, bar, ...values} = ctx.args
  return {
    operation: 'PutItem',
    key: util.dynamodb.toMapValues({foo, bar}),
    attributeValues: util.dynamodb.toMapValues(values),
    condition: { expression: "attribute_not_exists(id)" }
  };
}

By default, if the condition check fails, the Amazon AppSync DynamoDB function provides an error in ctx.error. You can return the error for the mutation and the current value of the object in DynamoDB in a data field in the error section of the GraphQL response.

However, the Amazon AppSync DynamoDB function offers some additional features to help developers handle some common edge cases:

These are described in greater detail in the Handling a condition check failure section.

For more information about DynamoDB conditions expressions, see the DynamoDB ConditionExpressions documentation .

Specifying a condition

The PutItem, UpdateItem, and DeleteItem request objects all allow an optional condition section to be specified. If omitted, no condition check is made. If specified, the condition must be true for the operation to succeed.

A condition section has the following structure:

type ConditionCheckExpression = {
  expression: string;
  expressionNames?: { [key: string]: string};
  expressionValues?: { [key: string]: any};
  equalsIgnore?: string[];
  consistentRead?: boolean;
  conditionalCheckFailedHandler?: {
    strategy: 'Custom' | 'Reject';
    lambdaArn?: string;
  };
};

The following fields specify the condition:

The remaining fields tell the Amazon AppSync DynamoDB function how to handle a condition check failure:

Handling a condition check failure

When a condition check fails, the Amazon AppSync DynamoDB function can pass on the error for the mutation and the current value of the object by using the util.appendError utility. This adds the data field in the error section of the GraphQL response. However, the Amazon AppSync DynamoDB function offers some additional features to help developers handle some common edge cases:

The flowchart for this process is:

Checking for the desired result

When the condition check fails, the Amazon AppSync DynamoDB function performs a GetItem DynamoDB request to get the current value of the item from DynamoDB. By default, it uses a strongly consistent read, however this can be configured using the consistentRead field in the condition block and compare it against the expected result:

If the current state of the object in DynamoDB is different from the expected result, the Amazon AppSync DynamoDB function follows the configured strategy, to either reject the mutation or invoke a Lambda function to determine what to do next.

Following the “reject” strategy

When following the Reject strategy, the Amazon AppSync DynamoDB function returns an error for the mutation, and the current value of the object in DynamoDB is also returned in a data field in the error section of the GraphQL response. The item returned from DynamoDB is put through the function response handler to translate it into a format the client expects, and it is filtered by the selection set.

For example, given the following mutation request:

mutation {
    updatePerson(id: 1, name: "Steve", expectedVersion: 1) {
        Name
        theVersion
    }
}

If the item returned from DynamoDB looks like the following:

{
   "id" : { "S" : "1" },
   "name" : { "S" : "Steve" },
   "version" : { "N" : 8 }
}

And the function response handler looks like the following:

import { util } from '@aws-appsync/utils';
export function response(ctx) {
  const { version, ...values } = ctx.result;
  const result = { ...values, theVersion: version };
  if (ctx.error) {
    if (error) {
      return util.appendError(error.message, error.type, result, null);
    }
  }
  return result
}

The GraphQL response looks like the following:

{
  "data": null,
  "errors": [
    {
      "message": "The conditional request failed (Service: AmazonDynamoDBv2; Status Code: 400; Error Code: ConditionalCheckFailedException; Request ID: ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZ)"
      "errorType": "DynamoDB:ConditionalCheckFailedException",
      "data": {
        "Name": "Steve",
        "theVersion": 8
      },
      ...
    }
  ]
}

Also, if any fields in the returned object are filled by other resolvers and the mutation had succeeded, they won’t be resolved when the object is returned in the error section.

Following the “custom” strategy

When following the Custom strategy, the Amazon AppSync DynamoDB function invokes a Lambda function to decide what to do next. The Lambda function chooses one of the following options:

The Lambda invocation request

The Amazon AppSync DynamoDB function invokes the Lambda function specified in the lambdaArn. It uses the same service-role-arn configured on the data source. The payload of the invocation has the following structure:

{
    "arguments": { ... },
    "requestMapping": {... },
    "currentValue": { ... },
    "resolver": { ... },
    "identity": { ... }
}

The fields are defined as follows:

A full example of the payload:

{
    "arguments": {
        "id": "1",
        "name": "Steve",
        "expectedVersion": 1
    },
    "requestMapping": {
        "version" : "2017-02-28",
        "operation" : "PutItem",
        "key" : {
           "id" : { "S" : "1" }
        },
        "attributeValues" : {
           "name" : { "S" : "Steve" },
           "version" : { "N" : 2 }
        },
        "condition" : {
           "expression" : "version = :expectedVersion",
           "expressionValues" : {
               ":expectedVersion" : { "N" : 1 }
           },
           "equalsIgnore": [ "version" ]
        }
    },
    "currentValue": {
        "id" : { "S" : "1" },
        "name" : { "S" : "Steve" },
        "version" : { "N" : 8 }
    },
    "resolver": {
        "tableName": "People",
        "awsRegion": "us-west-2",
        "parentType": "Mutation",
        "field": "updatePerson",
        "outputType": "Person"
    },
    "identity": {
        "accountId": "123456789012",
        "sourceIp": "x.x.x.x",
        "user": "AIDAAAAAAAAAAAAAAAAAA",
        "userArn": "arn:aws:iam::123456789012:user/appsync"
    }
}

The Lambda Invocation Response

The Lambda function can inspect the invocation payload and apply any business logic to decide how the Amazon AppSync DynamoDB function should handle the failure. There are three options for handling the condition check failure:

Here is an example Lambda function to deal with a failed PutItem request. The business logic looks at who made the call. If it was made by jeffTheAdmin, it retries the request, updating the version and expectedVersion from the item currently in DynamoDB. Otherwise, it rejects the mutation.

exports.handler = (event, context, callback) => {
    console.log("Event: "+ JSON.stringify(event));

    // Business logic goes here.

    var response;
    if ( event.identity.user == "jeffTheAdmin" ) {
        response = {
            "action" : "retry",
            "retryMapping" : {
                "attributeValues" : event.requestMapping.attributeValues,
                "condition" : {
                    "expression" : event.requestMapping.condition.expression,
                    "expressionValues" : event.requestMapping.condition.expressionValues
                }
            }
        }
        response.retryMapping.attributeValues.version = { "N" : event.currentValue.version.N + 1 }
        response.retryMapping.condition.expressionValues[':expectedVersion'] = event.currentValue.version

    } else {
        response = { "action" : "reject" }
    }

    console.log("Response: "+ JSON.stringify(response))
    callback(null, response)
};

Transaction condition expressions

Transaction condition expressions are available in requests of all four types of operations in TransactWriteItems, namely, PutItem, DeleteItem, UpdateItem, and ConditionCheck.

For PutItem, DeleteItem, and UpdateItem, the transaction condition expression is optional. For ConditionCheck, the transaction condition expression is required.

Example 1

The following transactional DeleteItem function request handler does not have a condition expression. As a result, it deletes the item in DynamoDB.

import { util } from '@aws-appsync/utils';

export function request(ctx) {
  const { postId } = ctx.args;
  return {
    operation: 'TransactWriteItems',
    transactItems: [
      {
        table: 'posts',
        operation: 'DeleteItem',
        key: util.dynamodb.toMapValues({ postId }),
      }
    ],
  };
}

Example 2

The following transactional DeleteItem function request handler does have a transaction condition expression that allows the operation succeed only if the author of that post equals a certain name.

import { util } from '@aws-appsync/utils';

export function request(ctx) {
  const { postId, authorName} = ctx.args;
  return {
    operation: 'TransactWriteItems',
    transactItems: [
      {
        table: 'posts',
        operation: 'DeleteItem',
        key: util.dynamodb.toMapValues({ postId }),
        condition: util.transform.toDynamoDBConditionExpression({
          authorName: { eq: authorName },
        }),
      }
    ],
  };
}

If the condition check fails, it will cause TransactionCanceledException and the error detail will be returned in ctx.result.cancellationReasons. Note that by default, the old item in DynamoDB that made condition check fail will be returned in ctx.result.cancellationReasons.

Specifying a condition

The PutItem, UpdateItem, and DeleteItem request objects all allow an optional condition section to be specified. If omitted, no condition check is made. If specified, the condition must be true for the operation to succeed. The ConditionCheck must have a condition section to be specified. The condition must be true for the whole transaction to succeed.

A condition section has the following structure:

type TransactConditionCheckExpression = {
  expression: string;
  expressionNames?: { [key: string]: string };
  expressionValues?: { [key: string]: string };
  returnValuesOnConditionCheckFailure: boolean;
};

The following fields specify the condition:

Projections

When reading objects in DynamoDB using the GetItem, Scan, Query, BatchGetItem, and TransactGetItems operations, you can optionally specify a projection that identifies the attributes that you want. The projection property has the following structure, which is similar to filters:

type DynamoDBExpression = {
  expression: string;
  expressionNames?: { [key: string]: string}
};

The fields are defined as follows:

Example 1

The following example is a projection section for a JavaScript function in which only the attributes author and id are returned from DynamoDB:

projection : {
    expression : "#author, id",
    expressionNames : {
        "#author" : "author"
    }
}