DynamoDB Item-Based Actions
GetItem, PutItem, UpdateItem and DeleteItem each act on one item, addressed
by its full primary key. They're the cheapest way to read or write a single item
whose key you know.
Getting their differences right, especially Put vs Update, prevents a class of
accidental-data-loss bugs. For many items per call, DynamoDB adds
Query and Scan for reads, plus
batch and transactional operations.
What are DynamoDB's item-based operations?
GetItem: read one item by its full primary key.PutItem: create or completely replace one item.UpdateItem: create or modify specific attributes of one item in place.DeleteItem: remove one item by its full primary key.- All four require the complete primary key (partition key, plus sort key if the table has one), so each addresses exactly one item.
PutItemoverwrites the whole item;UpdateItemchanges only what you name. Confusing them is how attributes silently disappear.
The defining trait: one item, full key
Every item-based action targets a single item by its complete primary key. DynamoDB hashes the partition key and goes straight to that item, with no filtering or scanning. If you don't know the full key, reach for Query and Scan instead.
Say you run user accounts keyed by USER#<id>:
PK: USER#204 email, displayName, plan, createdAtGetItemonUSER#204→ that user, directly.DeleteItemonUSER#204→ removes that user.
Both need the exact key.
PutItem vs UpdateItem: the one that bites
PutItemwrites the entire item. IfUSER#204already exists and youPutItemwith just{email, displayName}, the existingplanandcreatedAtattributes are gone. A put replaces the whole item; it doesn't merge.UpdateItemchanges only what you name.UpdateItemwith aSET email = …leaves every other attribute untouched, and creates the item if it didn't exist (an upsert).
Rule of thumb: reach for UpdateItem to change an existing item, and use PutItem
only when you mean "write this item as the complete new state." Both accept a
condition expression such as "only if it
doesn't already exist".
Cost: one item, one hop
A GetItem on a 2 KB item costs 0.5 RCU eventually consistent or 1 RCU
strongly consistent: one 4 KB block, rounded up. That makes it the cheapest way to
read one item whose key you know.
For many items under one partition key, a Query is cheaper per item, because it
adds up their sizes before rounding. Ten 2 KB items cost 2.5 RCU eventually consistent
in one Query, against 5 for ten GetItem calls
(composite primary key).
If you know only the partition key and filter in application code, you pay for every
item the Query reads.
| Operation | Keys required | Typical use | Capacity shape |
|---|---|---|---|
GetItem | Full primary key | Point read by id | Item size, per 4 KB |
PutItem | Full primary key | Create or replace whole item | Larger of old and new item, per 1 KB |
UpdateItem | Full primary key | Patch attributes | Larger of item before/after, per 1 KB |
DeleteItem | Full primary key | Remove row | Size of the deleted item, per 1 KB |
Query + filter | Partition (+ optional sort condition) | Many items in one partition | Sum of items read, per 4 KB |
UpdateItem bills the whole item even when you change one attribute. Measure a
representative item in the item-size calculator,
then price a GetItem loop against one Query in the
pricing calculator.
Condition expressions on writes
PutItem, UpdateItem and DeleteItem accept optional
condition expressions. Typical patterns:
attribute_not_exists(pk)on put: create-only insert without a race.attribute_exists(pk)on update: refuse to create a stub accidentally.plan = :expectedPlanon update: optimistic concurrency; re-read and retry if another writer changed the plan first.status = :closedon delete: delete only a closed ticket.
Conditions add no separate read charge; DynamoDB evaluates them against the stored
item during the write. A write whose condition fails still consumes write capacity
and returns ConditionalCheckFailedException.
Build conditions visually in the
DynamoDB expression builder; copy the
ConditionExpression plus ExpressionAttributeNames and
ExpressionAttributeValues into your SDK call.
Idempotency and overwrite safety
PutItem without a condition is last-writer-wins on the whole item. For webhook
handlers or SQS consumers, guard puts with attribute_not_exists on a processed
marker, or SET processed = :true guarded by attribute_not_exists(processed).
When you need the previous attribute values for an audit log, add
ReturnValues on the same UpdateItem instead
of a preceding GetItem: one round trip, no read/write race.
Choosing the right item action
| Intent | Call | Guard |
|---|---|---|
| Read profile by user id | GetItem | none |
| Create user if absent | PutItem | attribute_not_exists(pk) |
| Change email, keep other fields | UpdateItem | optional email = :expectedOld |
| Replace entire config blob | PutItem | only when the payload is complete |
| Remove closed ticket | DeleteItem | status = :closed |
| Read 50 tickets by known keys | BatchGetItem | not 50× GetItem in serial |
Item-based actions in DynoTable
In DynoTable, open a row to read the item in Quick View, or choose Edit Item to change it. Stage changes queues the edit so you can review the attribute diff before you commit; Commit changes stages and commits in one gesture.
Either way, the commit writes your items as TransactWriteItems calls, each item
conditioned on being unchanged since you read it. So a committed edit bills as a
transactional write, 2 WCU per KB instead of 1.
Delete-and-commit (⌘⇧⌫) removes the selected rows right away, without the review pause; a staged delete (⌘⌫) waits in the diff with your other changes.

To write the same calls in code, assemble update and condition clauses in the expression builder, which emits an SDK v3 snippet, and convert a plain-JSON item into the API's typed format with the DynamoDB JSON converter.
Pitfalls + next steps
PutItemreplaces the whole item. To change a few fields without losing the rest, useUpdateItem.- You must know the full primary key. No key means Query or Scan, not an item action.
- Many items at once? Don't loop these one by one: batch operations fold them into fewer round trips.
- Need the old/new value back? Set
ReturnValuesinstead of a follow-upGetItem. - Related: query vs scan covers the read-many side.
Download DynoTable to read, edit and commit single items against your own tables, with staged edits shown as a diff before you commit.


