UpdateItem do DynamoDB com a AWS CLI

Cinco argumentos, três deles DynamoDB JSON, todos brigando com o seu shell: é isso que torna o aws dynamodb update-item chato, não a atualização em si. O que a CLI acrescenta em cima de qualquer outro cliente é um segundo lugar onde a requisição pode ser rejeitada, e um conjunto de códigos de saída preciso o bastante para dizer qual dos dois foi.

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

Executado contra um item que não tinha nem Genre nem Awards, esse comando imprime:

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

O ADD em um Awards ausente começou do zero, e os atributos voltaram na ordem do serviço, e não na ordem em que a expressão os escreveu. Não encaminhe isso para nada posicional.

Explicação

--key — a chave primária completa, em DynamoDB JSON. Passe apenas a chave de partição de uma tabela com chave composta e você recebe ValidationException: The number of conditions on the keys is invalid, não uma correspondência parcial.
--update-expression — cláusulas SET, ADD, REMOVE e DELETE, com alias via --expression-attribute-names. ADD #upd2 :updValue2 aqui é um incremento atômico em Awards; a gramática completa das cláusulas está em expressões de atualização.

Números são strings entre aspas, e a CLI verifica isso antes do DynamoDB. Escreva {"N":1994} em vez de {"N":"1994"} e nada sai da sua 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'>

O código de saída diz qual metade falhou. Essa rejeição do lado do cliente sai com 252. Uma requisição que o DynamoDB de fato respondeu e recusou sai com 254:
```
aws: [ERROR]: An error occurred (ValidationException) when calling the UpdateItem operation: Invalid UpdateExpression: Attribute name is a reserved keyword; reserved keyword: Year
```
Um 252 é sempre um bug no seu JSON. Um 254 pode ser uma condição que você deliberadamente esperava que falhasse, então scripts devem ramificar entre os dois em vez de ramificar por "diferente de zero".
Sem --return-values o comando não imprime absolutamente nada e sai com 0. Não existe uma linha "1 item atualizado" para dar grep, então silêncio é sucesso. UPDATED_NEW retorna apenas os atributos que a expressão tocou, que é a opção barata quando você só precisa do novo valor do contador.
Escape uma vez, depois use um arquivo. Coloque cada argumento JSON entre aspas simples para que o shell deixe " e $ em paz, e mova qualquer coisa longa para --expression-attribute-values file://values.json em vez de escapar duas vezes.
Semântica de upsert — o update-item cria o item quando a chave não existe, que é como Awards apareceu acima. Adicione --condition-expression "attribute_exists(Artist)" para torná-lo somente-atualização.

Nada aqui monta a expressão por você

Dos cinco clientes documentados neste site, exatamente um vai gerar uma UpdateExpression: o pacote expression do SDK do Go. Node, Python e Java todos te entregam a string para escrever. A CLI é o pior caso dos quatro, porque você também está escrevendo à mão os dois mapas de alias e o DynamoDB JSON, dentro de um shell que quer interpretar os mesmos caracteres.

O DynamoDB Expression Builder fecha essa lacuna: monte as cláusulas no navegador, copie um comando aws dynamodb update-item já com as aspas prontas. Para fazer a mesma edição contra uma tabela real sem escapar uma única aspa, baixe o DynoTable.

Guias relacionados

Expressões de atualização do DynamoDB — SET, ADD, REMOVE, DELETE e idiomas.
Entendendo ReturnValues — o que cada opção de --return-values te dá.
"Attribute name is a reserved keyword" — por que o mapa de aliases aqui não é opcional.
Erros de sintaxe "Invalid UpdateExpression" — os erros comuns de sintaxe de SET/ADD, decodificados.

Referências

Verificado pela última vez em 2026-07-28 contra a documentação oficial da AWS vinculada acima.