UpdateItem DynamoDB avec l'AWS CLI

Cinq arguments, dont trois en DynamoDB JSON, tous à se battre avec ton shell : voilà ce qui rend aws dynamodb update-item pénible, pas la mise à jour elle-même. Ce que la CLI ajoute par rapport à tous les autres clients, c'est un deuxième endroit où la requête peut être rejetée, et un jeu de codes de sortie assez précis pour te dire lequel des deux.

Code

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

Lancée sur un élément qui n'avait ni Genre ni Awards, cette commande affiche :

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

ADD sur un Awards absent l'a démarré à zéro, et les attributs sont revenus dans l'ordre du service plutôt que dans celui où l'expression les a écrits. N'envoie pas ça dans quoi que ce soit de positionnel.

Explication

--key — la clé primaire complète, en DynamoDB JSON. Ne passe que la clé de partition d'une table à clé composite et tu obtiens ValidationException: The number of conditions on the keys is invalid, pas une correspondance partielle.
--update-expression — les clauses SET, ADD, REMOVE et DELETE, aliasées via --expression-attribute-names. ADD #upd2 :updValue2 est ici un incrément atomique sur Awards ; la grammaire complète des clauses est dans les expressions de mise à jour.

Les nombres sont des chaînes entre guillemets, et la CLI le vérifie avant DynamoDB. Écris {"N":1994} au lieu de {"N":"1994"} et rien ne quitte ta machine :

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

Le code de sortie te dit quelle moitié a échoué. Ce rejet côté client sort en 252. Une requête à laquelle DynamoDB a réellement répondu en la refusant sort en 254 :
```
aws: [ERROR]: An error occurred (ValidationException) when calling the UpdateItem operation: Invalid UpdateExpression: Attribute name is a reserved keyword; reserved keyword: Year
```
Un 252 est toujours un bug dans ton JSON. Un 254 peut être une condition dont tu attendais délibérément l'échec : les scripts devraient donc discriminer les deux plutôt que tester « différent de zéro ».
Sans --return-values, la commande n'affiche strictement rien et sort en 0. Il n'y a pas de ligne « 1 élément mis à jour » à grepper : le silence, c'est le succès. UPDATED_NEW ne renvoie que les attributs touchés par l'expression, l'option économique quand tu n'as besoin que de la nouvelle valeur du compteur.
Quote une fois, puis passe par un fichier. Mets chaque argument JSON entre guillemets simples pour que le shell laisse " et $ tranquilles, et déplace tout ce qui est long dans --expression-attribute-values file://values.json plutôt que de l'échapper deux fois.
Sémantique d'upsert — update-item crée l'élément quand la clé est absente, et c'est ainsi qu'Awards est apparu ci-dessus. Ajoute --condition-expression "attribute_exists(Artist)" pour le rendre exclusivement modificateur.

Rien ici ne construit l'expression à ta place

Des cinq clients documentés sur ce site, exactement un génère une UpdateExpression : le package expression du SDK Go. Node, Python et Java te laissent tous écrire la chaîne. La CLI est le pire cas des quatre, parce que tu écris aussi à la main les deux maps d'alias et le DynamoDB JSON, à l'intérieur d'un shell qui veut interpréter les mêmes caractères.

Le DynamoDB Expression Builder comble ce vide : assemble les clauses dans le navigateur, copie une commande aws dynamodb update-item déjà quotée. Pour faire la même modification sur une vraie table sans échapper le moindre guillemet, télécharge DynoTable.

Guides liés

Les expressions de mise à jour DynamoDB — SET, ADD, REMOVE, DELETE, et les idiomes.
Comprendre ReturnValues — ce que chaque option --return-values te donne.
"Attribute name is a reserved keyword" — pourquoi la map d'alias n'est pas optionnelle ici.
Les erreurs de syntaxe "Invalid UpdateExpression" — les fautes de syntaxe SET/ADD courantes, décodées.

Références

Dernière vérification le 2026-07-28 par rapport à la documentation officielle AWS liée ci-dessus.