How to Use UpdateItem in DynamoDB: Syntax and Example

Use the UpdateItem operation in DynamoDB to modify attributes of an existing item by specifying the table name, key, update expression, and optionally condition expressions. This lets you update, add, or delete attributes atomically without replacing the entire item.

Syntax

The UpdateItem operation requires these main parts:

• TableName: The name of your DynamoDB table.
• Key: The primary key of the item to update.
• UpdateExpression: A string that defines the attributes to update and how.
• ExpressionAttributeValues: Values used in the update expression.
• ConditionExpression (optional): A condition that must be true for the update to happen.
• ReturnValues (optional): What data to return after update, e.g., updated attributes.

json

UpdateItem {
  TableName: string,
  Key: { [attributeName]: { S: string } | { N: string } | ... },
  UpdateExpression: string,
  ExpressionAttributeValues: { [placeholder]: { S: string } | { N: string } | ... },
  ConditionExpression?: string,
  ReturnValues?: string
}

Example

This example updates the "Age" attribute of a user with UserId "123" by adding 1 to the current age. It returns the updated attributes.

javascript

const { DynamoDBClient, UpdateItemCommand } = require("@aws-sdk/client-dynamodb");

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

async function updateUserAge() {
  const params = {
    TableName: "Users",
    Key: {
      "UserId": { S: "123" }
    },
    UpdateExpression: "SET Age = Age + :inc",
    ExpressionAttributeValues: {
      ":inc": { N: "1" }
    },
    ReturnValues: "UPDATED_NEW"
  };

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

updateUserAge();

Output

Update succeeded: { Age: { N: '31' } }

Common Pitfalls

• Missing or incorrect key: The Key must exactly match the primary key of the item.
• Wrong update expression syntax: The UpdateExpression must use correct syntax like SET, REMOVE, ADD, or DELETE.
• Not using ExpressionAttributeValues: Always use placeholders (like :val) in expressions and define them in ExpressionAttributeValues.
• Ignoring conditional updates: If you want to update only when certain conditions hold, use ConditionExpression to avoid overwriting unexpectedly.

javascript

/* Wrong way: Missing ExpressionAttributeValues */
const paramsWrong = {
  TableName: "Users",
  Key: { "UserId": { S: "123" } },
  UpdateExpression: "SET Age = Age + :inc"
};

/* Right way: Include ExpressionAttributeValues */
const paramsRight = {
  TableName: "Users",
  Key: { "UserId": { S: "123" } },
  UpdateExpression: "SET Age = Age + :inc",
  ExpressionAttributeValues: { ":inc": { N: "1" } }
};

Quick Reference

Parameter	Description	Example
TableName	Name of the DynamoDB table	"Users"
Key	Primary key of the item to update	{"UserId": {S: "123"}}
UpdateExpression	Defines attribute updates	"SET Age = Age + :inc"
ExpressionAttributeValues	Values for placeholders in expressions	{":inc": {N: "1"}}
ConditionExpression	Optional condition to allow update	"attribute_exists(UserId)"
ReturnValues	What to return after update	"UPDATED_NEW"

Key Takeaways

Always specify the primary key of the item you want to update in the Key parameter.

Use UpdateExpression with placeholders and define them in ExpressionAttributeValues for safe updates.

Use ConditionExpression to prevent unwanted overwrites by checking conditions before updating.

ReturnValues lets you get the updated attributes without fetching the whole item again.

Check syntax carefully to avoid common errors like missing ExpressionAttributeValues or wrong UpdateExpression.