Beginner7 min read

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.
  • PutItem overwrites the whole item; UpdateItem changes 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, createdAt
  • GetItem on USER#204 → that user, directly.
  • DeleteItem on USER#204 → removes that user.

Both need the exact key.

PutItem vs UpdateItem: the one that bites

  • PutItem writes the entire item. If USER#204 already exists and you PutItem with just {email, displayName}, the existing plan and createdAt attributes are gone. A put replaces the whole item; it doesn't merge.
  • UpdateItem changes only what you name. UpdateItem with a SET email = … leaves every other attribute untouched, and creates the item if it didn't exist (an upsert).
Replace whole itemChange some attributes, keepthe restModify one existing item?PutItemUpdateItem

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.

OperationKeys requiredTypical useCapacity shape
GetItemFull primary keyPoint read by idItem size, per 4 KB
PutItemFull primary keyCreate or replace whole itemLarger of old and new item, per 1 KB
UpdateItemFull primary keyPatch attributesLarger of item before/after, per 1 KB
DeleteItemFull primary keyRemove rowSize of the deleted item, per 1 KB
Query + filterPartition (+ optional sort condition)Many items in one partitionSum 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 = :expectedPlan on update: optimistic concurrency; re-read and retry if another writer changed the plan first.
  • status = :closed on 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

IntentCallGuard
Read profile by user idGetItemnone
Create user if absentPutItemattribute_not_exists(pk)
Change email, keep other fieldsUpdateItemoptional email = :expectedOld
Replace entire config blobPutItemonly when the payload is complete
Remove closed ticketDeleteItemstatus = :closed
Read 50 tickets by known keysBatchGetItemnot 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.

Reading a single item in DynoTable's Quick View, with Edit Item and Copy as JSON actions.
Reading a single item in DynoTable's Quick View, with Edit Item and Copy as JSON actions.

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

  • PutItem replaces the whole item. To change a few fields without losing the rest, use UpdateItem.
  • 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 ReturnValues instead of a follow-up GetItem.
  • 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.

By Dmitriy · Updated