DynamoDB Conditional Write with the AWS CLI

A conditional write attaches a --condition-expression to put-item, update-item, or delete-item: DynamoDB evaluates it against the current item and applies the write only if it holds — atomically, with no read-modify-write race. It's DynamoDB's optimistic-locking primitive. This example guards an update with a version check.

Code

aws dynamodb update-item \
  --table-name 'Music' \
  --key '{"Artist":{"S":"Arturo Sandoval"},"SongTitle":{"S":"Cubano Chant"}}' \
  --update-expression 'SET #upd0 = :updValue0, #version = :newVersion' \
  --condition-expression 'attribute_exists(#cond0) AND #version = :expectedVersion' \
  --expression-attribute-names '{"#upd0":"Genre","#version":"Version","#cond0":"Artist"}' \
  --expression-attribute-values '{":updValue0":{"S":"Latin Jazz"},":expectedVersion":{"N":"7"},":newVersion":{"N":"8"}}'

On success the command prints nothing and exits 0. If another writer got there first, the condition fails:

An error occurred (ConditionalCheckFailedException) when calling the UpdateItem operation:
The conditional request failed

Explanation

• --condition-expression — checked against the stored item atomically with the write. Available functions: attribute_exists, attribute_not_exists, attribute_type, contains, begins_with, size, plus comparators (=, <>, <, >, <=, >=, BETWEEN, IN) and AND/OR/NOT.
• The two workhorse idioms:
  • attribute_exists(#key) on an update = "update-only, never create". Without it, update-item on a missing key silently creates the item (the accidental-upsert bug).
  • attribute_not_exists(#key) on a put = "create-only, never overwrite" — shown on the PutItem page.
• Optimistic locking — read the item (version 7), then write with #version = :expectedVersion while bumping to 8. Two concurrent writers can't both win; the loser exits non-zero with ConditionalCheckFailedException, re-reads, and retries on the new version.
• --return-values-on-condition-check-failure ALL_OLD — asks DynamoDB to attach the current item to the failure (valid values ALL_OLD | NONE; no read capacity consumed). The SDKs surface that item on the exception; the CLI's default error output prints just the message, so scripts usually re-read with get-item after a failure.
• A failed conditional write still bills the write attempt — don't use conditions as a free existence probe.

Do it visually

Condition expressions are exactly what the DynamoDB Expression Builder builds — pick the function, get the expression + name/value maps as a ready-to-run CLI command.

To edit items with generated, reviewable expressions instead of shell-quoted placeholders — download DynoTable.

Related examples

• DynamoDB conditional write in Node.js — the same optimistic lock with AWS SDK v3.
• DynamoDB conditional write in Python — the same optimistic lock with boto3.
• DynamoDB PutItem with the AWS CLI — the create-only attribute_not_exists put.
• DynamoDB condition expressions — every function, with patterns.
• Understanding ReturnValues — what each return option gives you.
• DynamoDB ConditionalCheckFailedException — when the failed check is expected, and how to handle it cheaply.

References

• UpdateItem — Amazon DynamoDB API Reference
• update-item — AWS CLI Command Reference
• Condition expressions — Amazon DynamoDB Developer Guide
• DynamoDB read and write operations (capacity unit consumption) — Amazon DynamoDB Developer Guide

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