DynamoDB BatchGetItem com a AWS CLI

aws dynamodb batch-get-item busca até 100 itens por chave primária em um único comando. Duas coisas o separam de query e scan na linha de comando: as chaves são JSON do DynamoDB aninhado que precisa sobreviver ao escape de aspas do shell, e a CLI não vai esvaziar UnprocessedKeys por você. Os limites e as regras de resultado parcial estão em operações em lote no DynamoDB.

Código

aws dynamodb batch-get-item \
  --request-items '{
    "Music": {
      "Keys": [
        {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}},
        {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "A Mis Abuelos"}},
        {"Artist": {"S": "Ella Fitzgerald"}, "SongTitle": {"S": "Misty"}}
      ]
    }
  }'

De forma abreviada, a saída mapeia cada tabela para os itens encontrados mais o que sobrou. A execução literal completa está mais abaixo na página:

{
    "Responses": {
        "Music": [
            {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}, ...}
        ]
    },
    "UnprocessedKeys": {}
}

Explicação

A CLI não tem nenhum mecanismo de paginação para este comando. aws dynamodb query help lista --starting-token, --max-items e --page-size; aws dynamodb batch-get-item help não lista nenhum dos três. UnprocessedKeys não é um token de paginação e a CLI trata a chamada como única, então esvaziá-lo é o seu loop de shell, não uma flag.
O mapa de sobras já vem no formato de entrada. Um UnprocessedKeys não vazio pode ser realimentado diretamente como --request-items sem nenhuma remodelagem, que é o que torna tolerável um loop while em bash. Espere entre as tentativas; uma reexecução imediata atinge a mesma partição com throttle.
ProjectionExpression e ConsistentRead vão dentro do objeto de cada tabela, ao lado de "Keys". Colocá-los no nível superior de --request-items é o erro de formato mais comum aqui.
Mantenha o mapa em um arquivo. --request-items file://keys.json elimina completamente o escape de aspas do shell, e é a única opção sensata a partir de um punhado de chaves. É também como você atinge o teto de 100 chaves sem perceber.

O que o comando realmente imprime

O bloco acima, executado literalmente contra o DynamoDB Local 3.3.0 com as três músicas presentes (aws-cli/2.36.9):

{
    "Responses": {
        "Music": [
            {
                "Artist": {"S": "Arturo Sandoval"},
                "AlbumTitle": {"S": "Danzon"},
                "Year": {"N": "1994"},
                "SongTitle": {"S": "A Mis Abuelos"}
            },
            {
                "Artist": {"S": "Ella Fitzgerald"},
                "AlbumTitle": {"S": "Ella in Berlin"},
                "Year": {"N": "1960"},
                "SongTitle": {"S": "Misty"}
            },
            {
                "Artist": {"S": "Arturo Sandoval"},
                "AlbumTitle": {"S": "Danzon"},
                "Year": {"N": "1994"},
                "SongTitle": {"S": "Cubano Chant"}
            }
        ]
    },
    "UnprocessedKeys": {}
}

(Cada mapa de atributos dobrado em uma única linha; todo o resto é como foi impresso.) O comando pediu Cubano Chant primeiro e o recebeu por último. Nada na resposta é posicional, então uma expressão jq que indexa .Responses.Music[0] está lendo o item que o serviço resolveu retornar primeiro. Filtre pelos atributos de chave em vez disso.

Duas requisições ele rejeita de cara, impressas em stderr com status de saída 254:

aws: [ERROR]: An error occurred (ValidationException) when calling the BatchGetItem operation: Provided list of item keys contains duplicates
aws: [ERROR]: An error occurred (ValidationException) when calling the BatchGetItem operation: Too many items requested for the BatchGetItem call

O prefixo aws: [ERROR]: é o wrapper da CLI v2; o texto depois dele é a mensagem do próprio serviço. Um loop de retry que trate qualquer saída diferente de zero como throttling vai girar para sempre em qualquer um dos dois, então ramifique pela mensagem antes de aplicar backoff.

Escrever à mão aquele JSON aninhado dentro de aspas simples é de onde vem a maior parte dos erros. O DynamoDB Expression Builder monta mapas de chave tipados e copia um comando pronto para executar, o que pelo menos tira o escape de aspas da lista de suspeitos.

Para ler um conjunto de chaves de volta e ver os itens sem o vaivém de JSON, baixe o DynoTable.

Exemplos relacionados

DynamoDB BatchGetItem em Node.js — a mesma leitura em lote com o AWS SDK v3.
DynamoDB BatchGetItem em Python — a mesma leitura em lote com boto3.
DynamoDB GetItem com a AWS CLI — a leitura de item único que isto agrupa em lote.
Operações em lote no DynamoDB — limites, falha parcial e quando o lote compensa.
"Too many items requested for the BatchGetItem call" — mais de 100 chaves em uma única requisição.
"Provided list of item keys contains duplicates" — a mesma chave duas vezes em um lote.

Referências

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