UpdateItem de DynamoDB con la AWS CLI

Cinco argumentos, tres de ellos DynamoDB JSON, todos peleándose con tu shell: eso es lo que hace delicado a aws dynamodb update-item, no la actualización en sí. Lo que la CLI añade por encima de cualquier otro cliente es un segundo lugar donde la petición puede ser rechazada, y un conjunto de códigos de salida lo bastante preciso para decirte cuál de los dos fue.

Código

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

Ejecutado contra un Item que no tenía ni Genre ni Awards, ese comando imprime:

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

ADD sobre un Awards ausente lo arrancó desde cero, y los atributos volvieron en el orden del servicio y no en el orden en que los escribió la expresión. No canalices esto hacia nada posicional.

Explicación

--key — la clave principal completa, en DynamoDB JSON. Pasa solo la clave de partición de una tabla con clave compuesta y obtienes ValidationException: The number of conditions on the keys is invalid, no una coincidencia parcial.
--update-expression — cláusulas SET, ADD, REMOVE y DELETE, con alias vía --expression-attribute-names. ADD #upd2 :updValue2 es aquí un incremento atómico sobre Awards; la gramática completa de las cláusulas está en expresiones de actualización.

Los números son cadenas entrecomilladas, y la CLI lo comprueba antes que DynamoDB. Escribe {"N":1994} en vez de {"N":"1994"} y no sale nada de tu máquina:

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

El código de salida te dice qué mitad falló. Ese rechazo del lado del cliente sale con 252. Una petición que DynamoDB sí respondió y rechazó sale con 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 siempre es un bug en tu JSON. Un 254 puede ser una condición que esperabas que fallara deliberadamente, así que los scripts deberían ramificar según cuál de los dos sea, y no según «distinto de cero».
Sin --return-values el comando no imprime absolutamente nada y sale con 0. No hay ninguna línea de «1 Item actualizado» que buscar con grep, así que el silencio es el éxito. UPDATED_NEW devuelve solo los atributos que tocó la expresión, que es la opción barata cuando solo necesitas el nuevo valor del contador.
Entrecomilla una vez y luego usa un fichero. Pon cada argumento JSON entre comillas simples para que la shell deje en paz " y $, y mueve cualquier cosa larga a --expression-attribute-values file://values.json en vez de escaparla dos veces.
Semántica de upsert — update-item crea el Item cuando la clave no existe, que es como apareció Awards arriba. Añade --condition-expression "attribute_exists(Artist)" para que sea solo de actualización.

Aquí nada construye la expresión por ti

De los cinco clientes documentados en este sitio, exactamente uno generará una UpdateExpression: el paquete expression del SDK de Go. Node, Python y Java te dejan la cadena para que la escribas tú. La CLI es el peor caso de los cuatro, porque además escribes a mano ambos mapas de alias y el DynamoDB JSON, dentro de una shell que quiere interpretar los mismos caracteres.

El DynamoDB Expression Builder cierra ese hueco: ensambla las cláusulas en el navegador y copia un comando aws dynamodb update-item ya entrecomillado. Para hacer la misma edición contra una tabla real sin escapar una sola comilla, descarga DynoTable.

Guías relacionadas

Expresiones de actualización de DynamoDB — SET, ADD, REMOVE, DELETE e idiomas.
Entender ReturnValues — qué te da cada opción de --return-values.
«Attribute name is a reserved keyword» — por qué el mapa de alias de aquí no es opcional.
Errores de sintaxis «Invalid UpdateExpression» — los fallos de sintaxis habituales de SET/ADD, descifrados.

Referencias

Verificado por última vez el 2026-07-28 contra la documentación oficial de AWS enlazada arriba.