用 AWS CLI 執行 DynamoDB BatchWriteItem

aws dynamodb batch-write-item 會在一條指令中放入或刪除最多 25 個項目。從 shell 用它有兩個 SDK 幫你磨圓、但這裡很銳利的邊角：每一個值都是你得正確加引號的 DynamoDB JSON，而且 CLI 完全沒有任何抽乾 UnprocessedItems 的機制。限制與部分失敗模型請見 DynamoDB 的批次操作。

程式碼

aws dynamodb batch-write-item \
  --request-items '{
    "Music": [
      {"PutRequest": {"Item": {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}, "AlbumTitle": {"S": "Danzon"}, "Year": {"N": "1994"}}}},
      {"PutRequest": {"Item": {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "A Mis Abuelos"}, "AlbumTitle": {"S": "Danzon"}, "Year": {"N": "1994"}}}},
      {"DeleteRequest": {"Key": {"Artist": {"S": "Ella Fitzgerald"}, "SongTitle": {"S": "Misty"}}}}
    ]
  }'

對 DynamoDB Local 3.3.0 執行，它印出的全部內容是：

{
    "UnprocessedItems": {}
}

說明

一份空的剩餘對應表，是你唯一能拿到的成功訊號。這條指令只印出 UnprocessedItems，別的什麼都沒有，所以一個只檢查結束狀態的腳本，會把只寫了一半的批次判定為成功。請解析那份對應表；jq -e '.UnprocessedItems | length == 0' 就是完整的檢查。
沒有任何旗標能把它抽乾。aws dynamodb query help 提供 --starting-token、--max-items 與 --page-size；aws dynamodb batch-write-item help 一個都沒有，因為 UnprocessedItems 不是分頁游標。把它餵回去是一個帶 sleep 的 shell 迴圈，而且它本來就已經是 --request-items 的形狀。
--condition-expression 與 --return-values 在這裡不被接受，而這是 API 的限制而非 CLI 的：條件無法掛在個別的 put 與 delete 請求上。每一個 PutRequest 都會取代整個已儲存的項目，所以用部分酬載組出來的批次，會把它沒帶到的屬性刪掉。
請用 file://，別用行內 JSON。--request-items file://writes.json 把 shell 引號從「可能出錯的東西」清單裡移除，而這很重要，因為這條指令出的錯大多都是引號問題。
一筆壞的項目，賠上全部 25 筆。資料表不存在、索引鍵與結構不符、單一項目超過 400 KB、總量超過 16 MB、分割區索引鍵超過 2048 位元組或排序索引鍵超過 1024 位元組，每一種都會回絕整個批次，而不只是那筆出問題的。

這條指令印出什麼，包含那些被回絕的

在上面那段程式碼加上 --return-consumed-capacity TOTAL，DynamoDB Local 3.3.0 的回答是：

{
    "UnprocessedItems": {},
    "ConsumedCapacity": [
        {
            "TableName": "Music",
            "CapacityUnits": 3.0
        }
    ]
}

兩次 put 加一次 delete 換來三個單位：批次買到的是一次來回，不是折扣。每一筆都按它所代表的個別 PutItem 或 DeleteItem 計費，並無條件進位到 1 KB。

在 Ella Fitzgerald / Misty 已經不在之後再跑一次刪除，DynamoDB Local 對那一個 DeleteRequest 回報 2.0 個單位。BatchWriteItem 參考文件（2026-07-28 取得）說對不存在項目的刪除會消耗一個寫入容量單位，而對同一個本機引擎執行獨立的 delete-item 確實回報 1.0。請把本機的容量數字當作方向性參考。不論哪一邊成立，能站得住腳的重點是：什麼都沒找到的刪除，一樣要計費。

有兩種請求服務會直接拒絕，出現在 stderr，結束狀態 254：

aws: [ERROR]: An error occurred (ValidationException) when calling the BatchWriteItem operation: Too many items requested for the BatchWriteItem call
aws: [ERROR]: An error occurred (ValidationException) when calling the BatchWriteItem operation: Provided list of item keys contains duplicates

第二個值得盯著看。它是由同一個索引鍵上的一個 PutRequest 加一個 DeleteRequest 產生的，不是兩次 put。DynamoDB 把同一批次中對同一項目的任何第二個操作都算成重複，所以「刪掉舊的那列、寫入新的」在單一批次裡會失敗，即使那兩筆看起來一點都不像。

時間都花在單引號裡組那些值的對應表上。DynamoDB Expression Builder 會產生型別化的對應表，並複製出一條可直接執行的指令，這樣失敗至少是真的失敗，而不是某個走失的反斜線。

想從 CSV 或 JSON 大量載入或清除項目，而完全不必逃逸任何字元，請下載 DynoTable。

參考資料

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

用 AWS CLI 執行 DynamoDB BatchWriteItem

程式碼

說明

這條指令印出什麼，包含那些被回絕的

相關範例

參考資料