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

Resolver mapping template reference for DynamoDB

The Amazon AppSync DynamoDB resolver 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 mapping templates for supported DynamoDB operations.

GetItem

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

The GetItem mapping document has the following structure:

{
    "version" : "2017-02-28",
    "operation" : "GetItem",
    "key" : {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "consistentRead" : true,
    "projection" : {
        ...
    }
}

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 mapping context ($context.result).

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

For more information about response mapping templates, see Resolver mapping template overview.

Example

The following example is a mapping template for a GraphQL query getThing(foo: String!, bar: String!):

{
    "version" : "2017-02-28",
    "operation" : "GetItem",
    "key" : {
        "foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
        "bar" : $util.dynamodb.toDynamoDBJson($ctx.args.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 resolver to make a PutItem request to DynamoDB, and enables you to specify the following:

The PutItem mapping document has the following structure:

{
    "version" : "2018-05-29",
    "operation" : "PutItem",
    "customPartitionKey" : "foo",
    "populateIndexFields" : boolean value,
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "attributeValues" : {
        "baz" : ... typed value
    },
    "condition" : {
       ...
    },
    "_version" : 1
}

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 mapping context ($context.result).

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

For more information about response mapping templates, see Resolver mapping template overview.

Example 1

The following example is a mapping template 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.

{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key": {
        "foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
        "bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
    },
    "attributeValues" : {
        "name"    : $util.dynamodb.toDynamoDBJson($ctx.args.name),
        "version" : $util.dynamodb.toDynamoDBJson($ctx.args.version)
    }
}

Example 2

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

This example checks to be sure the item currently in DynamoDB has the version field set to expectedVersion.

{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key": {
        "foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
        "bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
    },
    "attributeValues" : {
        "name"    : $util.dynamodb.toDynamoDBJson($ctx.args.name),
        #set( $newVersion = $context.arguments.expectedVersion + 1 )
        "version" : $util.dynamodb.toDynamoDBJson($newVersion)
    },
    "condition" : {
        "expression" : "version = :expectedVersion",
        "expressionValues" : {
            ":expectedVersion" : $util.dynamodb.toDynamoDBJson($expectedVersion)
        }
    }
}

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

UpdateItem

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

The UpdateItem mapping document has the following structure:

{
    "version" : "2018-05-29",
    "operation" : "UpdateItem",
    "customPartitionKey" : "foo",
    "populateIndexFields" : boolean value,
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "update" : {
        "expression" : "someExpression",
        "expressionNames" : {
           "#foo" : "foo"
       },
       "expressionValues" : {
           ":bar" : ... typed value
       }
    },
    "condition" : {
        ...
    },
    "_version" : 1
}

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 mapping context ($context.result).

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

For more information about response mapping templates, see Resolver mapping template overview.

Example 1

The following example is a mapping template for the GraphQL mutation upvote(id: ID!).

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

{
    "version" : "2017-02-28",
    "operation" : "UpdateItem",
    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    },
    "update" : {
        "expression" : "ADD #votefield :plusOne, version :plusOne",
        "expressionNames" : {
            "#votefield" : "upvotes"
        },
        "expressionValues" : {
            ":plusOne" : { "N" : 1 }
        }
    }
}

Example 2

The following example is a mapping template 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:

{
    "version" : "2017-02-28",

    "operation" : "UpdateItem",

    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    },

    ## Set up some space to keep track of things we're updating **
    #set( $expNames  = {} )
    #set( $expValues = {} )
    #set( $expSet = {} )
    #set( $expAdd = {} )
    #set( $expRemove = [] )

    ## Increment "version" by 1 **
    $!{expAdd.put("version", ":newVersion")}
    $!{expValues.put(":newVersion", { "N" : 1 })}

    ## Iterate through each argument, skipping "id" and "expectedVersion" **
    #foreach( $entry in $context.arguments.entrySet() )
        #if( $entry.key != "id" && $entry.key != "expectedVersion" )
            #if( (!$entry.value) && ("$!{entry.value}" == "") )
                ## If the argument is set to "null", then remove that attribute from the item in DynamoDB **

                #set( $discard = ${expRemove.add("#${entry.key}")} )
                $!{expNames.put("#${entry.key}", "$entry.key")}
            #else
                ## Otherwise set (or update) the attribute on the item in DynamoDB **

                $!{expSet.put("#${entry.key}", ":${entry.key}")}
                $!{expNames.put("#${entry.key}", "$entry.key")}

                #if( $entry.key == "ups" || $entry.key == "downs" )
                    $!{expValues.put(":${entry.key}", { "N" : $entry.value })}
                #else
                    $!{expValues.put(":${entry.key}", { "S" : "${entry.value}" })}
                #end
            #end
        #end
    #end

    ## Start building the update expression, starting with attributes we're going to SET **
    #set( $expression = "" )
    #if( !${expSet.isEmpty()} )
        #set( $expression = "SET" )
        #foreach( $entry in $expSet.entrySet() )
            #set( $expression = "${expression} ${entry.key} = ${entry.value}" )
            #if ( $foreach.hasNext )
                #set( $expression = "${expression}," )
            #end
        #end
    #end

    ## Continue building the update expression, adding attributes we're going to ADD **
    #if( !${expAdd.isEmpty()} )
        #set( $expression = "${expression} ADD" )
        #foreach( $entry in $expAdd.entrySet() )
            #set( $expression = "${expression} ${entry.key} ${entry.value}" )
            #if ( $foreach.hasNext )
                #set( $expression = "${expression}," )
            #end
        #end
    #end

    ## Continue building the update expression, adding attributes we're going to REMOVE **
    #if( !${expRemove.isEmpty()} )
        #set( $expression = "${expression} REMOVE" )

        #foreach( $entry in $expRemove )
            #set( $expression = "${expression} ${entry}" )
            #if ( $foreach.hasNext )
                #set( $expression = "${expression}," )
            #end
        #end
    #end

    ## Finally, write the update expression into the document, along with any expressionNames and expressionValues **
    "update" : {
        "expression" : "${expression}"
        #if( !${expNames.isEmpty()} )
            ,"expressionNames" : $utils.toJson($expNames)
        #end
        #if( !${expValues.isEmpty()} )
            ,"expressionValues" : $utils.toJson($expValues)
        #end
    },

    "condition" : {
        "expression"       : "version = :expectedVersion",
        "expressionValues" : {
            ":expectedVersion" : $util.dynamodb.toDynamoDBJson($ctx.args.expectedVersion)
        }
    }
}

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

DeleteItem

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

The DeleteItem mapping document has the following structure:

{
    "version" : "2018-05-29",
    "operation" : "DeleteItem",
    "customPartitionKey" : "foo",
    "populateIndexFields" : boolean value,
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "condition" : {
        ...
    },
    "_version" : 1
}

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 mapping context ($context.result).

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

For more information about response mapping templates, see Resolver mapping template overview.

Example 1

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

{
    "version" : "2017-02-28",
    "operation" : "DeleteItem",
    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    }
}

Example 2

The following example is a mapping template 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:

{
    "version" : "2017-02-28",
    "operation" : "DeleteItem",
    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    },
    "condition" : {
        "expression"       : "attribute_not_exists(id) OR version = :expectedVersion",
        "expressionValues" : {
            ":expectedVersion" : $util.dynamodb.toDynamoDBJson($expectedVersion)
        }
    }
}

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

Query

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

The Query mapping document has the following structure:

{
    "version" : "2017-02-28",
    "operation" : "Query",
    "query" : {
        "expression" : "some expression",
        "expressionNames" : {
            "#foo" : "foo"
        },
        "expressionValues" : {
            ":bar" : ... typed value
        }
    },
    "index" : "fooIndex",
    "nextToken" : "a pagination token",
    "limit" : 10,
    "scanIndexForward" : true,
    "consistentRead" : false,
    "select" : "ALL_ATTRIBUTES" | "ALL_PROJECTED_ATTRIBUTES" | "SPECIFIC_ATTRIBUTES",
    "filter" : {
        ...
    },
    "projection" : {
        ...
    }
}

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 mapping context ($context.result).

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

For more information about response mapping templates, see Resolver mapping template 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 mapping template 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.

{
    "version" : "2017-02-28",
    "operation" : "Query",
    "query" : {
        "expression" : "ownerId = :ownerId",
        "expressionValues" : {
            ":ownerId" : $util.dynamodb.toDynamoDBJson($context.arguments.owner)
        }
    },
    "index" : "owner-index"
}

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

Scan

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

The Scan mapping document has the following structure:

{
    "version" : "2017-02-28",
    "operation" : "Scan",
    "index" : "fooIndex",
    "limit" : 10,
    "consistentRead" : false,
    "nextToken" : "aPaginationToken",
    "totalSegments" : 10,
    "segment" : 1,
    "filter" : {
        ...
    },
    "projection" : {
        ...
    }
}

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 mapping context ($context.result).

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

For more information about response mapping templates, see Resolver mapping template 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 mapping template for the GraphQL query: allPosts.

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

{
    "version" : "2017-02-28",
    "operation" : "Scan"
}

Example 2

The following example is a mapping template 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.

{
    "version" : "2017-02-28",
    "operation" : "Scan",
    "filter" : {
        "expression" : "begins_with(title, :title)",
        "expressionValues" : {
            ":title" : $util.dynamodb.toDynamoDBJson($context.arguments.title)
        },
    }
}

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

Sync

The Sync request mapping document 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 mapping document has the following structure:

{
    "version" : "2018-05-29",
    "operation" : "Sync",
    "basePartitionKey": "Base Tables PartitionKey",
    "deltaIndexName": "delta-index-name",
    "limit" : 10,
    "nextToken" : "aPaginationToken",
    "lastSync" :  1550000000000,
    "filter" : {
        ...
    }
}

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 mapping context ($context.result).

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

For more information about response mapping templates, see Resolver mapping template 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 mapping template 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.

{
    "version" : "2018-05-29",
    "operation" : "Sync",
    "limit": 100,
    "nextToken": $util.toJson($util.defaultIfNull($ctx.args.nextToken, null)),
    "lastSync": $util.toJson($util.defaultIfNull($ctx.args.lastSync, null))
}

BatchGetItem

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

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

The BatchGetItem mapping document has the following structure:

{
    "version" : "2018-05-29",
    "operation" : "BatchGetItem",
    "tables" : {
        "table1": {
           "keys": [
              ## Item to retrieve Key
              {
                   "foo" : ... typed value,
                   "bar" : ... typed value
              },
              ## Item2 to retrieve Key
              {
                   "foo" : ... typed value,
                   "bar" : ... typed value
              }
            ],
            "consistentRead": true|false,            
            "projection" : {
                 ...
            }
        },
        "table2": {
           "keys": [
              ## Item3 to retrieve Key
              {
                   "foo" : ... typed value,
                   "bar" : ... typed value
              },
              ## Item4 to retrieve Key
              {
                   "foo" : ... typed value,
                   "bar" : ... typed value
              }
            ],
            "consistentRead": true|false,
            "projection" : {
                 ...
            }
        }
    }
}

The fields are defined as follows:

BatchGetItem fields

Things to remember:

For the following example request mapping template:

{
  "version": "2018-05-29",
  "operation": "BatchGetItem",
  "tables": {
    "authors": [
        {
          "author_id": {
            "S": "a1"
          }
        },
    ],
    "posts": [
        {
          "author_id": {
            "S": "a1"
          },
          "post_id": {
            "S": "p2"
          }
        }
    ],
  }
}

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

{
   "data": {
     "authors": [null],
     "posts": [
        # Was retrieved
        {
          "author_id": "a1",
          "post_id": "p2",
          "post_title": "title",
          "post_description": "description",
        }
     ]
   },
   "unprocessedKeys": {
     "authors": [
        # This item was not processed due to an error
        {
          "author_id": "a1"
        }
      ],
     "posts": []
   }
}

The $ctx.error contains details about the error. The keys data, unprocessedKeys, and each table key that was provided in the request mapping template 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.

For a more complete example, follow the DynamoDB Batch tutorial with AppSync here Tutorial: DynamoDB batch resolvers.

BatchDeleteItem

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

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

The BatchDeleteItem mapping document has the following structure:

{
    "version" : "2018-05-29",
    "operation" : "BatchDeleteItem",
    "tables" : {
        "table1": [
        ## Item to delete Key
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        },
        ## Item2 to delete Key
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        }],
        "table2": [
        ## Item3 to delete Key
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        },
        ## Item4 to delete Key
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        }],
    }
}

The fields are defined as follows:

BatchDeleteItem fields

Things to remember:

For the following example request mapping template:

{
  "version": "2018-05-29",
  "operation": "BatchDeleteItem",
  "tables": {
    "authors": [
        {
          "author_id": {
            "S": "a1"
          }
        },
    ],
    "posts": [
        {
          "author_id": {
            "S": "a1"
          },
          "post_id": {
            "S": "p2"
          }
        }
    ],
  }
}

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

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

The $ctx.error contains details about the error. The keys data, unprocessedKeys, and each table key that was provided in the request mapping template 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.

For a more complete example, follow the DynamoDB Batch tutorial with AppSync here Tutorial: DynamoDB batch resolvers.

BatchPutItem

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

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

The BatchPutItem mapping document has the following structure:

{
    "version" : "2018-05-29",
    "operation" : "BatchPutItem",
    "tables" : {
        "table1": [
        ## Item to put
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        },
        ## Item2 to put
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        }],
        "table2": [
        ## Item3 to put
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        },
        ## Item4 to put
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        }],
    }
}

The fields are defined as follows:

BatchPutItem fields

Things to remember:

For the following example request mapping template:

{
  "version": "2018-05-29",
  "operation": "BatchPutItem",
  "tables": {
    "authors": [
        {
          "author_id": {
            "S": "a1"
          },
          "author_name": {
            "S": "a1_name"
          }
        },
    ],
    "posts": [
        {
          "author_id": {
            "S": "a1"
          },
          "post_id": {
            "S": "p2"
          },
          "post_title": {
            "S": "title"
          }
        }
    ],
  }
}

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

{
   "data": {
     "authors": [
         null
     ],
     "posts": [
        # Was inserted
        {
          "author_id": "a1",
          "post_id": "p2",
          "post_title": "title"
        }
     ]
   },
   "unprocessedItems": {
     "authors": [
        # This item was not processed due to an error
        {
          "author_id": "a1",
          "author_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 mapping template 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.

For a more complete example, follow the DynamoDB Batch tutorial with AppSync here Tutorial: DynamoDB batch resolvers.

TransactGetItems

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

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

The TransactGetItems mapping document has the following structure:

{
    "version": "2018-05-29",
    "operation": "TransactGetItems",
    "transactItems": [
       ## First request item
       {
           "table": "table1",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           },
           "projection" : {
                ...
           }
       },
       ## Second request item
       {
           "table": "table2",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           },
           "projection" : {
                ...
           }
       }
    ]
}

The fields are defined as follows:

TransactGetItems fields

Things to remember:

For the following example request mapping template:

{
    "version": "2018-05-29",
    "operation": "TransactGetItems",
    "transactItems": [
       ## First request item
       {
           "table": "posts",
           "key": {
               "post_id": {
                 "S": "p1"
               }
           }
       },
       ## Second request item
       {
           "table": "authors",
           "key": {
               "author_id": {
                 "S": a1
               }
           }
       }
    ]
}

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.

For a more complete example, follow the DynamoDB Transaction tutorial with AppSync here Tutorial: DynamoDB transaction resolvers.

TransactWriteItems

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

The DynamoDB TransactWriteItems limits apply.

The TransactWriteItems mapping document has the following structure:

{
    "version": "2018-05-29",
    "operation": "TransactWriteItems",
    "transactItems": [
       {
           "table": "table1",
           "operation": "PutItem",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           },
           "attributeValues": {
               "baz": ... typed value
           },
           "condition": {
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       },
       {
           "table":"table2",
           "operation": "UpdateItem",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           },
           "update": {
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               }
           },
           "condition": {
               "expression": "someExpression",
               "expressionNames": {
                   "#foo":"foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       },
       {
           "table": "table3",
           "operation": "DeleteItem",
           "key":{
               "foo": ... typed value,
               "bar": ... typed value
           },
           "condition":{
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       },
       {
           "table": "table4",
           "operation": "ConditionCheck",
           "key":{
               "foo": ... typed value,
               "bar": ... typed value
           },
           "condition":{
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       }
    ]
}

TransactWriteItems fields

Things to remember:

For the following example request mapping template:

{
    "version": "2018-05-29",
    "operation": "TransactWriteItems",
    "transactItems": [
       {
           "table": "posts",
           "operation": "PutItem",
           "key": {
               "post_id": {
                   "S": "p1"
               }
           },
           "attributeValues": {
               "post_title": {
                   "S": "New title"
               },
               "post_description": {
                   "S": "New description"
               }
           },
           "condition": {
               "expression": "post_title = :post_title",
               "expressionValues": {
                   ":post_title": {
                       "S": "Expected old title"
                   }
               }
           }
       },
       {
           "table":"authors",
           "operation": "UpdateItem",
           "key": {
               "author_id": {
                   "S": "a1"
               },
           },
           "update": {
               "expression": "SET author_name = :author_name",
               "expressionValues": {
                   ":author_name": {
                       "S": "New name"
                   }
               }
           },
       }
    ]
}

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.

For a more complete example, follow the DynamoDB Transaction tutorial with AppSync here Tutorial: DynamoDB transaction resolvers.

Type system (request mapping)

When using the Amazon AppSync DynamoDB resolver 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 mapping document isn’t parsed.

A DynamoDB value is used anywhere in a request mapping document 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 mapping document).

"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 mapping context.

For example, if DynamoDB returns the following:

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

Then the Amazon AppSync DynamoDB resolver 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 mapping section of a Query or Scan mapping document has the following structure:

"filter" : {
    "expression" : "filter expression"
    "expressionNames" : {
        "#name" : "name",
    },
    "expressionValues" : {
        ":value" : ... typed value
    },
}

The fields are defined as follows:

Example

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

"filter" : {
    "expression" : "begins_with(#title, :title)",
    "expressionNames" : {
        "#title" : "title"
    },
    "expressionValues" : {
        ":title" : $util.dynamodb.toDynamoDBJson($context.arguments.title)
    }
}

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 resolver allows a condition expression to be specified in PutItem, UpdateItem, and DeleteItem request mapping documents, and also a strategy to follow if the condition fails and the object was not updated.

Example 1

The following PutItem mapping document 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.

{
   "version" : "2017-02-28",
   "operation" : "PutItem",
   "key" : {
      "id" : { "S" : "1" }
   }
}

Example 2

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

{
   "version" : "2017-02-28",
   "operation" : "PutItem",
   "key" : {
      "id" : { "S" : "1" }
   },
   "condition" : {
      "expression" : "attribute_not_exists(id)"
   }
}

By default, if the condition check fails, the Amazon AppSync DynamoDB resolver returns an 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 resolver 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 mapping documents 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:

"condition" : {
    "expression" : "someExpression"
    "expressionNames" : {
        "#foo" : "foo"
    },
    "expressionValues" : {
        ":bar" : ... typed value
    },
    "equalsIgnore" : [ "version" ],
    "consistentRead" : true,
    "conditionalCheckFailedHandler" : {
        "strategy" : "Custom",
        "lambdaArn" : "arn:..."
    }
}

The following fields specify the condition:

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

Handling a condition check failure

By default, when a condition check fails, the Amazon AppSync DynamoDB resolver returns an 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 resolver 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 resolver 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 resolver 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 resolver 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 response mapping template 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 response mapping template looks like the following:

{
   "id" : $util.toJson($context.result.id),
   "Name" : $util.toJson($context.result.name),
   "theVersion" : $util.toJson($context.result.version)
}

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 resolver 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 resolver 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 resolver 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 request mapping templates 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 mapping document does not have a condition expression. As a result, it deletes the item in DynamoDB.

{
   "version": "2018-05-29",
   "operation": "TransactWriteItems",
   "transactItems": [
      {
         "table": "posts",
         "operation": "DeleteItem",
         "key": {
            "id": { "S" : "1" }
         }
      }
   ]
}

Example 2

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

{
   "version": "2018-05-29",
   "operation": "TransactWriteItems",
   "transactItems": [
      {
         "table": "posts",
         "operation": "DeleteItem",
         "key": {
            "id": { "S" : "1" }
         }
         "condition": {
            "expression": "author = :author",
            "expressionValues": {
               ":author": { "S" : "Chunyan" }
            }
         }
      }
   ]
}

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 mapping documents 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:

"condition": {
    "expression": "someExpression",
    "expressionNames": {
        "#foo": "foo"
    },
    "expressionValues": {
        ":bar": ... typed value
    },
    "returnValuesOnConditionCheckFailure": false
}

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 has the following structure, which is similar to filters:

"projection" : {
    "expression" : "projection expression"
    "expressionNames" : {
        "#name" : "name",
    }
}

The fields are defined as follows:

Example 1

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

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