使用 AWS CLI 執行 DynamoDB 條件式寫入

條件式寫入是把 --condition-expression 附加到 put-item、update-item 或 delete-item 上：DynamoDB 會對目前的項目評估它，只有在成立時才套用寫入 — 以 atomic 方式進行，沒有 read-modify-write 競爭。這是 DynamoDB 的樂觀鎖基本手法。本範例以版本檢查為一次更新加上守衛。

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"}}'

成功時，指令不印出任何內容並以 0 結束。若另一位寫入者搶先一步，條件會失敗：

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

說明

--condition-expression — 與寫入以 atomic 方式一起對已儲存的項目檢查。可用的函式：attribute_exists、attribute_not_exists、attribute_type、contains、begins_with、size，以及比較運算子（=、<>、<、>、<=、>=、BETWEEN、IN）與 AND/OR/NOT。
兩個主力慣用手法：
- 在更新上使用 attribute_exists(#key) = 「只更新、絕不建立」。沒有它，對缺少的 key 執行 update-item 會靜默建立該項目（意外 upsert 的 bug）。
- 在 put 上使用 attribute_not_exists(#key) = 「只建立、絕不覆寫」— 見 PutItem 頁面。
樂觀鎖 — 讀取項目（版本 7），然後在寫入時以 #version = :expectedVersion 檢查並把版本推進到 8。兩個並行的寫入者不可能都贏；輸家會以非零狀態退出並帶著 ConditionalCheckFailedException，接著重新讀取、在新版本上重試。
--return-values-on-condition-check-failure ALL_OLD — 請 DynamoDB 把目前的項目附在失敗上（有效值 ALL_OLD | NONE；不消耗讀取容量）。SDK 會在例外上呈現該項目；CLI 預設的錯誤輸出只印出訊息，所以指令稿通常在失敗後以 get-item 重新讀取。
失敗的條件式寫入仍會對寫入嘗試計費 — 別把條件當成免費的存在探測。

改用視覺化操作

條件運算式正是 DynamoDB Expression Builder 所建立的 — 選擇函式，取得運算式與 name/value map，形成一個可直接執行的 CLI 指令。

想以產生且可審視的運算式編輯項目，而非 shell 引號的佔位符 — 下載 DynoTable。

References

最後驗證於 2026-07-13，對照上方連結的 AWS 官方文件。

使用 AWS CLI 執行 DynamoDB 條件式寫入

Code

說明

改用視覺化操作

相關範例

References