使用 AWS CLI 執行 DynamoDB UpdateItem

五個參數，其中三個是 DynamoDB JSON，而且全都在跟你的 shell 過不去：這才是 aws dynamodb update-item 麻煩的地方，不是更新本身。CLI 在其他每一種用戶端之上多加的，是第二個請求可能被拒絕的地點，以及一組精確到足以告訴你是哪一邊出錯的結束代碼。

程式碼

aws dynamodb update-item \
  --table-name 'Music' \
  --key '{"Artist":{"S":"Arturo Sandoval"},"SongTitle":{"S":"Cubano Chant"}}' \
  --update-expression 'SET #upd0 = :updValue0, #upd1 = :updValue1 ADD #upd2 :updValue2' \
  --expression-attribute-names '{"#upd0":"Genre","#upd1":"Year","#upd2":"Awards"}' \
  --expression-attribute-values '{":updValue0":{"S":"Latin Jazz"},":updValue1":{"N":"1994"},":updValue2":{"N":"1"}}' \
  --return-values ALL_NEW

對一個原本既沒有 Genre 也沒有 Awards 的項目執行，那個指令會印出：

{
    "Attributes": {
        "Artist": {
            "S": "Arturo Sandoval"
        },
        "Awards": {
            "N": "1"
        },
        "Genre": {
            "S": "Latin Jazz"
        },
        "Year": {
            "N": "1994"
        },
        "SongTitle": {
            "S": "Cubano Chant"
        }
    }
}

ADD 作用在不存在的 Awards 上時會從零起算，而各屬性回來的順序是服務的順序，不是運算式寫入的順序。別把這個接進任何依位置取值的東西。

說明

--key — 完整的 primary key，以 DynamoDB JSON 表示。對一張複合鍵表格只傳 partition key，你得到的是 ValidationException: The number of conditions on the keys is invalid，不是部分比對。
--update-expression — SET、ADD、REMOVE 與 DELETE 子句，透過 --expression-attribute-names 取別名。這裡的 ADD #upd2 :updValue2 是對 Awards 的原子式遞增；完整的子句文法在更新運算式裡。

數字是加了引號的字串，而且 CLI 會比 DynamoDB 更早檢查這件事。寫成 {"N":1994} 而不是 {"N":"1994"}，就沒有任何東西會離開你的機器：

aws: [ERROR]: An error occurred (ParamValidation): Parameter validation failed:
Invalid type for parameter ExpressionAttributeValues.:y.N, value: 1994, type: <class 'int'>, valid types: <class 'str'>

結束代碼會告訴你是哪一半失敗的。那個用戶端側的拒絕結束於 252。一個 DynamoDB 真的回答了、並且拒絕的請求則結束於 254：
```
aws: [ERROR]: An error occurred (ValidationException) when calling the UpdateItem operation: Invalid UpdateExpression: Attribute name is a reserved keyword; reserved keyword: Year
```
252 一定是你 JSON 裡的 bug。254 則可能是你刻意預期會失敗的條件，所以指令碼應該對這兩者分支，而不是對「非零」分支。
不加 --return-values，指令什麼都不會印出，並以 0 結束。沒有一行「已更新 1 個項目」可以 grep，所以沉默就是成功。UPDATED_NEW 只回傳運算式動到的那些屬性，當你只需要新的計數值時，那是便宜的選項。
先把引號處理好，然後改用檔案。為每個 JSON 參數加上單引號，讓 shell 別碰 " 與 $，並把任何過長的內容移進 --expression-attribute-values file://values.json，而不是把它跳脫兩次。
upsert 語意 — 當那個鍵不存在時，update-item 會建立項目，上面的 Awards 就是這樣冒出來的。加上 --condition-expression "attribute_exists(Artist)" 可以讓它變成僅更新。

這裡沒有任何東西會替你組出運算式

本站記載的五種用戶端中，恰好只有一種會產生 UpdateExpression：Go SDK 的 expression 套件。Node、Python 與 Java 都是把字串丟給你自己寫。CLI 是這四者中最糟的情況，因為你還要在一個會去解讀同樣那些字元的 shell 裡，親手寫出兩份別名對應與 DynamoDB JSON。

DynamoDB Expression Builder 填補了這個落差：在瀏覽器裡把子句組起來，複製一個引號已經處理好的 aws dynamodb update-item 指令。若想對真正的表格做同一次編輯、而且不必跳脫任何一個引號，請下載 DynoTable。

參考資料

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

使用 AWS CLI 執行 DynamoDB UpdateItem

程式碼

說明

這裡沒有任何東西會替你組出運算式

相關指南

參考資料