DynamoDB PutItem vs UpdateItem: Which Write Should You Use?

DynamoDB PutItem creates an item or completely replaces the item with the same primary key. UpdateItem changes selected attributes and can also create an item if it is missing. Both support conditions, and neither charges only for the attributes you send: replacing or updating an existing item uses the larger of its size before and after the write.

PutItem vs UpdateItem at a glance

The API names use PutItem and UpdateItem. In the JavaScript v3 document client, their commands are PutCommand and UpdateCommand; the low-level client uses PutItemCommand and UpdateItemCommand. In Python, the boto3 table methods are put_item and update_item.

DynamoDB UpdateItem

Use UpdateItem when you know the attributes you want to change. You do not need to fetch the item first to change its topic, add a publication date, increment a counter, or remove an obsolete field. Attributes outside the expression remain intact.

An update is an upsert by default. Add attribute_exists(ArticleId) when an absent article should be an error. Otherwise a typo in the key can create a new item containing only that key and the attributes your expression supplies. An expression that depends on a missing attribute or map can still fail; upsert does not initialize every document path automatically.

SDK v3 example: update an article

The examples use an Article table with a string partition key named ArticleId. Configure AWS credentials and a Region through your normal SDK configuration. Install @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb for JavaScript.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, UpdateCommand } from "@aws-sdk/lib-dynamodb"

const db = DynamoDBDocumentClient.from(new DynamoDBClient({}))

const result = await db.send(new UpdateCommand({
  TableName: "Article",
  Key: { ArticleId: "A001" },
  UpdateExpression: "SET #topic = :topic, #date = :date",
  ConditionExpression: "attribute_exists(ArticleId)",
  ExpressionAttributeNames: { "#topic": "Topic", "#date": "Date" },
  ExpressionAttributeValues: { ":topic": "DynamoDB", ":date": "2026-10-23" },
  ReturnValues: "ALL_NEW",
  ReturnConsumedCapacity: "TOTAL",
  ReturnValuesOnConditionCheckFailure: "ALL_OLD",
}))

console.log(result.Attributes)
console.log(result.ConsumedCapacity)
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, UpdateCommand } from "@aws-sdk/lib-dynamodb"

const db = DynamoDBDocumentClient.from(new DynamoDBClient({}))

const result = await db.send(new UpdateCommand({
  TableName: "Article",
  Key: { ArticleId: "A001" },
  UpdateExpression: "SET #topic = :topic, #date = :date",
  ConditionExpression: "attribute_exists(ArticleId)",
  ExpressionAttributeNames: { "#topic": "Topic", "#date": "Date" },
  ExpressionAttributeValues: { ":topic": "DynamoDB", ":date": "2026-10-23" },
  ReturnValues: "ALL_NEW",
  ReturnConsumedCapacity: "TOTAL",
  ReturnValuesOnConditionCheckFailure: "ALL_OLD",
}))

console.log(result.Attributes)
console.log(result.ConsumedCapacity)

This updates Topic and Date, preserves fields such as Writer, and returns the complete resulting item. The document client accepts ordinary JavaScript values; do not wrap them in low-level descriptors such as S or N.

UpdateItem request parameters

• TableName selects the table; Key identifies one item. Include both partition and sort keys on a composite-key table.
• UpdateExpression describes the changes. ExpressionAttributeNames aliases attribute names, and ExpressionAttributeValues supplies typed values through placeholders.
• ConditionExpression must be true for the write to happen. The condition and update are evaluated atomically for that item.
• ReturnValues controls the successful response's Attributes. ReturnValuesOnConditionCheckFailure controls the old item returned with a failed condition.
• ReturnConsumedCapacity accepts NONE, TOTAL or INDEXES. Use INDEXES when you need table and index capacity details.
• ReturnItemCollectionMetrics: "SIZE" requests item-collection size estimates for tables with local secondary indexes.

The UpdateItem API reference lists the complete request and response shapes. Prefer expressions over the legacy AttributeUpdates and Expected parameters.

Atomic counters, lists, sets and maps

An update expression can combine SET, REMOVE, ADD and DELETE, with each action keyword appearing once. These examples show expressions and the corresponding document-client values:

Map aliases to their attribute names in ExpressionAttributeNames. A nested map such as details must already exist before you update details.editor; initialize the map on creation or handle that case separately. ADD works on numbers and sets, while DELETE subtracts set members. REMOVE deletes an entire attribute or a list element. The UpdateExpression guide covers every action and function in depth.

A counter increment is atomic, but repeating the request increments it again. A timeout can leave you unsure whether a write succeeded. For business-critical increments, use an idempotency record in a transaction or an expected version condition instead of assuming an automatic retry is harmless.

DynamoDB PutItem

Use PutItem when you have the complete desired item. If A001 currently has Topic, Writer and Date, putting only ArticleId and Topic removes Writer and Date. DynamoDB does not merge the supplied object with the old item.

Both TableName and Item are required. Within Item, every primary-key attribute is required; the remaining fields depend on your application. Omitting ArticleId would fail validation.

SDK v3 example: create without overwriting

import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb"

const db = DynamoDBDocumentClient.from(new DynamoDBClient({}))

await db.send(new PutCommand({
  TableName: "Article",
  Item: {
    ArticleId: "A001",
    Topic: "DynamoDB",
    Writer: "Chameera",
    Date: "2026-10-23",
  },
  ConditionExpression: "attribute_not_exists(ArticleId)",
  ReturnConsumedCapacity: "TOTAL",
  ReturnValuesOnConditionCheckFailure: "ALL_OLD",
}))
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb"

const db = DynamoDBDocumentClient.from(new DynamoDBClient({}))

await db.send(new PutCommand({
  TableName: "Article",
  Item: {
    ArticleId: "A001",
    Topic: "DynamoDB",
    Writer: "Chameera",
    Date: "2026-10-23",
  },
  ConditionExpression: "attribute_not_exists(ArticleId)",
  ReturnConsumedCapacity: "TOTAL",
  ReturnValuesOnConditionCheckFailure: "ALL_OLD",
}))

The condition makes this create-only. Remove it only when replacing an existing item is intended. To replace a particular revision, use an expected version condition and include the new version in the replacement. See conditional writes for the expression patterns and optimistic locking for conflict handling.

PutItem request parameters and response elements

PutItem shares the condition, expression-placeholder, consumed-capacity and item-collection options described above. It takes Item instead of Key plus UpdateExpression.

On success, Attributes is present only when ReturnValues: "ALL_OLD" was requested and an old item existed. PutItem does not accept ALL_NEW: your request already contains the new item. ConsumedCapacity and ItemCollectionMetrics are optional, controlled by their request settings, rather than three fields guaranteed on every response. See the PutItem API reference.

For both operations, returned attributes do not consume extra read capacity. Successful return values reflect the write consistently. Failed-condition returns are a separate setting, accept NONE or ALL_OLD, and can save a follow-up read when investigating a conflict. Do not log the returned item indiscriminately if it contains private data.

Python examples with boto3

The resource interface uses native Python values. For non-integer numbers, use Decimal instead of a Python float.

import boto3
from botocore.exceptions import ClientError

table = boto3.resource("dynamodb").Table("Article")

try:
    table.put_item(
        Item={"ArticleId": "A001", "Topic": "DynamoDB", "Writer": "Chameera"},
        ConditionExpression="attribute_not_exists(ArticleId)",
        ReturnValuesOnConditionCheckFailure="ALL_OLD",
    )
except ClientError as error:
    if error.response["Error"]["Code"] != "ConditionalCheckFailedException":
        raise
    print("Article already exists; updating its topic")

result = table.update_item(
    Key={"ArticleId": "A001"},
    UpdateExpression="SET #topic = :topic",
    ConditionExpression="attribute_exists(ArticleId)",
    ExpressionAttributeNames={"#topic": "Topic"},
    ExpressionAttributeValues={":topic": "DynamoDB writes"},
    ReturnValues="ALL_NEW",
)
print(result["Attributes"])
import boto3
from botocore.exceptions import ClientError

table = boto3.resource("dynamodb").Table("Article")

try:
    table.put_item(
        Item={"ArticleId": "A001", "Topic": "DynamoDB", "Writer": "Chameera"},
        ConditionExpression="attribute_not_exists(ArticleId)",
        ReturnValuesOnConditionCheckFailure="ALL_OLD",
    )
except ClientError as error:
    if error.response["Error"]["Code"] != "ConditionalCheckFailedException":
        raise
    print("Article already exists; updating its topic")

result = table.update_item(
    Key={"ArticleId": "A001"},
    UpdateExpression="SET #topic = :topic",
    ConditionExpression="attribute_exists(ArticleId)",
    ExpressionAttributeNames={"#topic": "Topic"},
    ExpressionAttributeValues={":topic": "DynamoDB writes"},
    ReturnValues="ALL_NEW",
)
print(result["Attributes"])

AWS CLI v2 examples

The CLI uses DynamoDB JSON with explicit type descriptors. These commands first create an article, then change one field. The create fails if the key already exists.

aws dynamodb put-item \
  --table-name Article \
  --item '{"ArticleId":{"S":"A001"},"Topic":{"S":"DynamoDB"},"Writer":{"S":"Chameera"}}' \
  --condition-expression 'attribute_not_exists(ArticleId)'

aws dynamodb update-item \
  --table-name Article \
  --key '{"ArticleId":{"S":"A001"}}' \
  --update-expression 'SET #topic = :topic' \
  --condition-expression 'attribute_exists(ArticleId)' \
  --expression-attribute-names '{"#topic":"Topic"}' \
  --expression-attribute-values '{":topic":{"S":"DynamoDB writes"}}' \
  --return-values ALL_NEW
aws dynamodb put-item \
  --table-name Article \
  --item '{"ArticleId":{"S":"A001"},"Topic":{"S":"DynamoDB"},"Writer":{"S":"Chameera"}}' \
  --condition-expression 'attribute_not_exists(ArticleId)'

aws dynamodb update-item \
  --table-name Article \
  --key '{"ArticleId":{"S":"A001"}}' \
  --update-expression 'SET #topic = :topic' \
  --condition-expression 'attribute_exists(ArticleId)' \
  --expression-attribute-names '{"#topic":"Topic"}' \
  --expression-attribute-values '{":topic":{"S":"DynamoDB writes"}}' \
  --return-values ALL_NEW

How PutItem and UpdateItem are billed

For a standard write, round the larger of the existing and resulting item sizes up to the next 1 KB. In provisioned mode, one WCU supports one such 1 KB write per second; on-demand mode charges write request units using the same size increments. Index changes can consume additional write capacity.

Changing a short field in a 6 KB item consumes 6 write units if the resulting item is no larger. Shrinking that item to 2 KB also consumes 6. A partial update saves request payload and avoids sending unchanged attributes, but it does not reduce the table write charge to the size of the changed field. AWS documents this in read and write capacity calculations.

Use the capacity and item-size calculator to estimate your item, including attribute names. Conditions that fail still consume capacity; they are concurrency controls, not free existence checks.

Which operation should you use?

Choose PutItem for new entities, complete document replacement, or immutable revision records. Choose UpdateItem for independent attribute changes, counters, collection edits and changes guarded by the current state. Neither operation changes an item's primary key; changing a key requires a new item and deletion of the old one.

For changes that must succeed together across several items, use DynamoDB transactions. A single-item write is already atomic, so a transaction adds no benefit when your entire invariant fits in one conditional update.