DynamoDB BatchWriteItem with the AWS CLI

aws dynamodb batch-write-item puts or deletes up to 25 items in a single command (16 MB total, 400 KB per item). The writes go in --request-items as a map of table → PutRequest/DeleteRequest entries in DynamoDB JSON — and you must check UnprocessedItems in the output, because the batch as a whole is not atomic.

Code

aws dynamodb batch-write-item \
  --request-items '{
    "Music": [
      {"PutRequest": {"Item": {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}, "AlbumTitle": {"S": "Danzon"}, "Year": {"N": "1994"}}}},
      {"PutRequest": {"Item": {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "A Mis Abuelos"}, "AlbumTitle": {"S": "Danzon"}, "Year": {"N": "1994"}}}},
      {"DeleteRequest": {"Key": {"Artist": {"S": "Ella Fitzgerald"}, "SongTitle": {"S": "Misty"}}}}
    ]
  }'

When everything lands, the output's leftover map is empty:

{
    "UnprocessedItems": {}
}

Explanation

• --request-items — a map of table name → an array of up to 25 PutRequest/DeleteRequest entries (one command can span multiple tables). Each PutRequest.Item needs the full primary key; each DeleteRequest.Key is just the key. Values are DynamoDB JSON — numbers are strings under N.
• Not a transaction — each put/delete is atomic individually, but the batch as a whole is not. Need all-or-nothing? Use transact-write-items.
• UnprocessedItems — the CLI does not auto-retry a partial batch. If the map is non-empty (throttling is the usual cause), re-run the command with that exact map as --request-items — it's already in the right form — backing off between attempts.
• No updates, no conditions — batch-write-item cannot express update-item, --condition-expression, or --return-values; a put on an existing key silently replaces the whole item. Duplicate keys, put+delete on the same item, >25 requests, a >400 KB item, or >16 MB total each cause DynamoDB to reject the entire batch.
• Tip: keep the map in a file and pass --request-items file://writes.json — shell-quoting 25 items inline is misery.

Do it visually

Hand-writing nested DynamoDB JSON in shell quotes is error-prone. The DynamoDB Expression Builder builds typed value maps and copies ready-to-run CLI commands, and the item size calculator checks each item against the 400 KB cap.

To bulk-add, edit, and delete items in a GUI — CSV/JSON import instead of JSON escaping — download DynoTable.

Related examples

• DynamoDB BatchWriteItem in Node.js — the same batch write with AWS SDK v3.
• DynamoDB batch write in Python — boto3's batch_writer() does the retry loop for you.
• DynamoDB PutItem with the AWS CLI — the single-item write this batches.
• Batch operations in DynamoDB — limits, partial failure, and when batching pays off.
• "Too many items requested for the BatchWriteItem call" — more than 25 put/delete requests in one batch.
• "Provided list of item keys contains duplicates" — two requests touching the same key in one batch.

References

• BatchWriteItem — Amazon DynamoDB API Reference
• batch-write-item — AWS CLI Command Reference
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide

Last verified 2026-07-13 against the official AWS documentation linked above.