GetItem do DynamoDB com a AWS CLI

Na CLI a chave é uma string DynamoDB JSON, com cada valor envolvido pelo seu tipo ({"S": "..."}, {"N": "..."}), o que significa que a maior parte da dificuldade em um aws dynamodb get-item está no escape do shell, e não no DynamoDB. A chave em si ainda precisa ser a chave primária completa.

Código

aws dynamodb get-item \
  --table-name 'Music' \
  --key '{"Artist":{"S":"Arturo Sandoval"},"SongTitle":{"S":"Cubano Chant"}}' \
  --projection-expression '#proj0, #proj1, #proj2, #proj3' \
  --expression-attribute-names '{"#proj0":"Artist","#proj1":"SongTitle","#proj2":"AlbumTitle","#proj3":"Year"}'

A resposta imprime o item em DynamoDB JSON:

{
  "Item": {
    "Artist": {"S": "Arturo Sandoval"},
    "SongTitle": {"S": "Cubano Chant"},
    "AlbumTitle": {"S": "Danzon"},
    "Year": {"N": "1994"}
  }
}

Explicação

Uma busca sem resultado não imprime absolutamente nada — nem Item, nem objeto vazio, código de saída 0. Encaminhar isso direto para o jq falha com entrada vazia, então capture a saída e teste a string antes de fazer o parse.
O escape é o trabalho de verdade — coloque o JSON entre aspas simples no bash e no zsh para que $ e ! fiquem literais. O cmd e o PowerShell do Windows seguem regras diferentes; coloque a chave em um arquivo e passe --key file://key.json em vez de brigar com eles.
--query não é --projection-expression — --query é JMESPath, aplicado na sua máquina depois que o item já foi lido e cobrado. --projection-expression é o que o DynamoDB enxerga. Nenhum dos dois reduz o custo de leitura (por quê).
Os aliases #proj0 são obrigatórios, não estilísticos — Year está na lista de palavras reservadas da AWS, e nomeá-la diretamente em uma projeção é rejeitado.
Pergunte quanto custou — adicione --return-consumed-capacity TOTAL e a resposta ganha um bloco ConsumedCapacity. Para este item, abaixo de 4 KB, isso dá 0,5 unidade de capacidade, ou 1,0 assim que você adiciona --consistent-read (o trade-off).
A CLI v2 pagina a sua saída — por padrão tudo passa pelo less no macOS e no Linux (com as flags FRX) ou pelo more no Windows. Em um script isso raramente é o que você quer: passe --no-cli-pager, ou defina AWS_PAGER como string vazia.

Faça isso visualmente

Digitar aquele bloco de --key na mão é onde o tempo se perde. O DynamoDB Expression Builder monta o DynamoDB JSON e os mapas de alias a partir de um formulário, e então devolve um comando aws dynamodb pronto para executar.

O DynoTable faz a mesma coisa contra uma tabela real: navegue pelas linhas em uma grade e depois exporte a consulta por trás delas como um comando de CLI. Baixe o DynoTable.

Guias relacionados

Query vs. Scan — quando um único get-item ganha de um query.
Como funcionam as chaves de partição do DynamoDB — por que o get-item precisa da chave completa.
DynamoDB ResourceNotFoundException — o primeiro erro habitual aqui: nome de tabela ou região errados.
"The provided key element does not match the schema" — a chave que você passa não corresponde ao schema de chave da tabela.

Referências

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