PutItem vs UpdateItem in DynamoDB: Key Differences and Usage

In DynamoDB, PutItem creates a new item or replaces an existing one entirely, while UpdateItem modifies specific attributes of an existing item without replacing the whole item. Use PutItem to overwrite or add items, and UpdateItem to change parts of an item safely.

Quick Comparison

This table summarizes the main differences between PutItem and UpdateItem in DynamoDB.

Feature	PutItem	UpdateItem
Operation Type	Creates or fully replaces an item	Modifies specific attributes of an existing item
Overwrite Behavior	Replaces entire item if it exists	Updates only specified attributes, keeps others intact
Conditional Writes	Supports conditions to prevent overwrite	Supports conditions to control attribute updates
Return Values	Can return old item before overwrite	Can return updated attributes or old values
Use Case	Insert new item or replace existing completely	Update or add attributes without affecting others

Key Differences

PutItem is used when you want to add a new item or completely replace an existing item in a DynamoDB table. If the item already exists, PutItem overwrites it entirely, removing any attributes not included in the new item. This means you lose any data not specified in the new request.

On the other hand, UpdateItem lets you change only certain attributes of an existing item without touching the rest. It can add new attributes, modify existing ones, or delete attributes selectively. This operation is safer when you want to keep other data intact.

Both operations support conditional expressions to control when the write happens, such as only updating if an attribute has a certain value. They also allow you to return the item's old or new state after the operation, which helps in verifying changes.

PutItem Code Example

python

import boto3

dynamodb = boto3.resource('dynamodb')
table = dynamodb.Table('Users')

response = table.put_item(
    Item={
        'UserId': '123',
        'Name': 'Alice',
        'Age': 30
    }
)
print('PutItem succeeded:', response)

Output

PutItem succeeded: {'ResponseMetadata': {'RequestId': '...', 'HTTPStatusCode': 200, ...}}

UpdateItem Equivalent

python

import boto3

dynamodb = boto3.resource('dynamodb')
table = dynamodb.Table('Users')

response = table.update_item(
    Key={'UserId': '123'},
    UpdateExpression='SET Age = :newAge',
    ExpressionAttributeValues={
        ':newAge': 31
    },
    ReturnValues='UPDATED_NEW'
)
print('UpdateItem succeeded:', response['Attributes'])

Output

UpdateItem succeeded: {'Age': 31}

When to Use Which

Choose PutItem when you want to add a new item or completely replace an existing item with fresh data. It is simple and effective if you don't need to preserve any existing attributes.

Choose UpdateItem when you want to change only certain parts of an item without affecting other data. This is safer for partial updates and avoids accidental data loss.

In summary, use PutItem for full replacements and UpdateItem for targeted attribute changes.

Key Takeaways

PutItem replaces the entire item or creates a new one.

UpdateItem modifies specific attributes without overwriting the whole item.

Use PutItem for full item replacement and UpdateItem for partial updates.

Both support conditional writes and returning item states after operation.

Choosing the right operation helps prevent accidental data loss.