How to Use list_append in DynamoDB for List Updates

In DynamoDB, list_append is used in an UpdateExpression to add elements to an existing list attribute. It appends one list to another, allowing you to extend lists without replacing them entirely. Use it with the SET action like SET listAttr = list_append(listAttr, :newItems).

Syntax

The list_append function takes two lists and returns a new list with the second list appended to the first. It is used inside an UpdateExpression with the SET keyword.

• list_append(list1, list2): Appends list2 to the end of list1.
• listAttr: The existing list attribute in your DynamoDB item.
• :newItems: A placeholder for the new list elements you want to add, passed as an expression attribute value.

sql

SET listAttr = list_append(listAttr, :newItems)

Example

This example shows how to append new items to a list attribute named Tags in a DynamoDB table called Products. It uses the AWS SDK for JavaScript v3 to update the item with ProductId '123'.

javascript

import { DynamoDBClient, UpdateItemCommand } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient({ region: "us-east-1" });

async function appendTags() {
  const params = {
    TableName: "Products",
    Key: {
      ProductId: { S: "123" }
    },
    UpdateExpression: "SET Tags = list_append(if_not_exists(Tags, :empty_list), :newTags)",
    ExpressionAttributeValues: {
      ":newTags": { L: [ { S: "NewTag1" }, { S: "NewTag2" } ] },
      ":empty_list": { L: [] }
    },
    ReturnValues: "UPDATED_NEW"
  };

  try {
    const data = await client.send(new UpdateItemCommand(params));
    console.log("Update succeeded:", JSON.stringify(data.Attributes));
  } catch (err) {
    console.error("Update failed:", err);
  }
}

appendTags();

Output

{"Tags":["ExistingTag1","ExistingTag2","NewTag1","NewTag2"]}

Common Pitfalls

Common mistakes when using list_append include:

• Trying to append to a list attribute that does not exist, which causes an error unless you use if_not_exists to provide a default empty list.
• Passing a single item instead of a list as the second argument; list_append requires both arguments to be lists.
• Confusing list_append with adding elements to a set; they are different data types in DynamoDB.

sql

/* Wrong: Passing a single string instead of a list */
UpdateExpression: "SET Tags = list_append(Tags, :newTag)",
ExpressionAttributeValues: {
  ":newTag": { S: "SingleTag" } // This should be a list
}

/* Right: Passing a list with one element */
UpdateExpression: "SET Tags = list_append(if_not_exists(Tags, :empty_list), :newTags)",
ExpressionAttributeValues: {
  ":newTags": { L: [ { S: "SingleTag" } ] },
  ":empty_list": { L: [] }
}

Quick Reference

Tips for using list_append effectively:

• Always ensure both arguments are lists.
• Use if_not_exists to handle missing list attributes safely.
• Use ReturnValues: "UPDATED_NEW" to get the updated list after the operation.
• Remember list_append adds items to the end of the list; to prepend, reverse the arguments.

Key Takeaways

Use list_append in UpdateExpression to add items to existing list attributes without overwriting.

Both arguments to list_append must be lists; wrap single items in a list structure.

Use if_not_exists to avoid errors when the list attribute might not exist yet.

list_append appends the second list to the first; reverse arguments to prepend items.

Return updated attributes with ReturnValues: "UPDATED_NEW" to confirm changes.