AWS CLI での DynamoDB UpdateItem

引数は 5 つ、うち 3 つは DynamoDB JSON、そのすべてがあなたのシェルと戦っている。aws dynamodb update-item を面倒にしているのは更新そのものではなく、これです。CLI が他のどのクライアントにも増して加えるのは、リクエストが拒否されうる 2 つ目の場所と、それがどちらだったのかを教えてくれるだけの精度を持つ終了コードの組です。

コード

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

存在しない Awards に対する ADD はゼロから始め、属性は式が書いた順ではなくサービス側の順で返ってきました。これを位置に依存する何かにパイプしてはいけません。

解説

--key — 完全なプライマリキーを DynamoDB JSON で。複合キーのテーブルにパーティションキーだけを渡すと、部分一致ではなく ValidationException: The number of conditions on the keys is invalid になります。
--update-expression — SET、ADD、REMOVE、DELETE の各句を、--expression-attribute-names を通じてエイリアスします。ここでの ADD #upd2 :updValue2 は Awards に対するアトミックなインクリメントです。句の完全な文法は更新式にあります。
数値はクォートした文字列で、しかも DynamoDB より先に CLI がそれを検査します。{"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 のバグです。254 は、意図的に失敗を想定していた条件かもしれません。ですからスクリプトは「ゼロ以外」ではなく、この 2 つで分岐すべきです。
--return-values がなければコマンドは何も表示せず、終了コード 0 で終わります。grep できる「1 件更新しました」の行はないので、沈黙が成功です。UPDATED_NEW は式が触れた属性だけを返すので、新しいカウンターの値だけが必要なときの安い選択肢です。
クォートは 1 回、その先はファイルへ。各 JSON 引数をシングルクォートで囲んでシェルに " と $ を触らせないようにし、長いものは二重にエスケープするのではなく --expression-attribute-values file://values.json に移しましょう。
アップサートのセマンティクス — update-item はキーが存在しないときアイテムを作成します。上で Awards が現れたのはそのためです。更新のみにするには --condition-expression "attribute_exists(Artist)" を足します。

ここでは誰も式を組み立ててくれない

このサイトで扱っている 5 つのクライアントのうち、UpdateExpression を生成してくれるのはちょうど 1 つ、Go SDK の expression パッケージだけです。Node、Python、Java はどれも文字列をあなたに書かせます。CLI はその 4 つの中で最悪のケースです。両方のエイリアスマップと DynamoDB JSON も手書きしなければならず、しかもそれを、同じ文字を解釈したがるシェルの中でやるからです。

DynamoDB Expression Builder はそのギャップを埋めます。ブラウザで句を組み立て、クォート済みの aws dynamodb update-item コマンドをコピーするだけです。同じ編集をシングルクォートのエスケープなしで実際のテーブルに対して行うには、DynoTable をダウンロードしてください。

参考資料

最終検証日 2026-07-28、上記にリンクした公式 AWS ドキュメントに照らして確認しました。

AWS CLI での DynamoDB UpdateItem

コード

解説

ここでは誰も式を組み立ててくれない

関連ガイド

参考資料