Query do DynamoDB com a AWS CLI

aws dynamodb query lê uma partição, opcionalmente estreitada pela chave de ordenação (Query vs Scan explica quando essa é a escolha certa, e expressões de condição de chave lista todos os operadores permitidos). O que a CLI acrescenta por cima é uma camada de paginação própria, e ela é a origem da maior parte das surpresas neste comando.

Código

aws dynamodb query \
  --table-name 'Music' \
  --key-condition-expression '#hashKey = :hashKeyValue AND begins_with(#rangeKey, :rangeKeyValue)' \
  --expression-attribute-names '{"#hashKey":"Artist","#rangeKey":"SongTitle"}' \
  --expression-attribute-values '{":hashKeyValue":{"S":"Arturo Sandoval"},":rangeKeyValue":{"S":"C"}}'

Os aliases #hashKey/#rangeKey resolvem para Artist/SongTitle através de --expression-attribute-names, que é o que impede uma palavra reservada de quebrar o comando. Adicione --no-scan-index-forward para ordem decrescente de chave de ordenação; a crescente é o padrão.

Paginação

Por padrão a CLI pagina automaticamente — ela segue o LastEvaluatedKey internamente e imprime o resultado combinado. Para paginar manualmente (por exemplo, com conjuntos de resultados grandes), controle assim:

aws dynamodb query \
  --table-name 'Music' \
  --key-condition-expression '#hashKey = :hashKeyValue' \
  --expression-attribute-names '{"#hashKey":"Artist"}' \
  --expression-attribute-values '{":hashKeyValue":{"S":"Arturo Sandoval"}}' \
  --page-size 100 \
  --max-items 50
# The output includes a "NextToken"; pass it back with --starting-token to continue.

Explicação

A CLI esconde a paginação, inclusive do número de custo. Semeamos uma partição com 30 itens de ~60 KB cada, cerca de 1,8 MB e, portanto, duas páginas de serviço, e então rodamos a mesma consulta de três formas com --return-consumed-capacity TOTAL:

default (auto-paginate)  Count: 30   CapacityUnits: 132.0   LastEvaluatedKey: null
--no-paginate            Count: 18   CapacityUnits: 132.0   LastEvaluatedKey: {…S017}
--max-items 3            Count: 18   items printed: 3       NextToken: eyJFeGNsdXNpdmVTdGFydEtleSI6…

Paginar à mão mostrou o custo real: a página 1 tinha 18 itens a 132,0 unidades, a página 2 tinha 12 itens a 88,0, então a consulta realmente consumiu 220,0 unidades de leitura. A execução com paginação automática fez as duas chamadas, devolveu todos os 30 itens e reportou 132,0. A CLI mescla Items e Count entre as páginas, mas não o ConsumedCapacity, então o número impresso subestima esta consulta em 40%. Se você está dimensionando capacidade a partir da saída da CLI, pagine manualmente ou vai dimensionar para uma página só.

--max-items é um limite de impressão. Não é um Limit. A terceira execução acima imprimiu três itens e ainda reportou Count: 18 e ScannedCount: 18, porque a página de serviço que ela truncou tinha 18 itens e aproximadamente 1 MB. Você pagou por tudo aquilo. O parâmetro do DynamoDB que de fato limita a leitura é o Limit, e a CLI o expõe como --page-size.

Ou seja, as duas flags fazem trabalhos sem relação. --page-size vira o Limit da API e muda o que cada chamada de serviço lê; --max-items só decide quanto do resultado mesclado chega ao seu terminal, e emite um NextToken para o restante. Esse token é um blob base64 da contabilidade da própria CLI, não o LastEvaluatedKey do DynamoDB, e ele volta por --starting-token.

Não existe --limit nem --exclusive-start-key. Rode aws dynamodb query help na 2.36.9 e nenhum dos dois aparece na sinopse: a CLI remove os dois parâmetros de paginação do DynamoDB e substitui pelos três dela. Então o loop natural — pegar o LastEvaluatedKey de uma chamada e alimentar a próxima — não tem flag para onde ser alimentado. O caminho de volta à API bruta é --cli-input-json, que recebe a requisição literalmente:

--cli-input-json with "Limit": 5 and an "ExclusiveStartKey"
  → Count: 5   CapacityUnits: 37.0   LastEvaluatedKey: {"Artist":…,"SongTitle":"S007"}

Note que isso também desligou o paginador: a execução devolveu uma página e um LastEvaluatedKey real mesmo sem --no-paginate. Se você está escrevendo um loop de shell sobre uma partição grande, --cli-input-json é a forma honesta, e --no-paginate é a rápida.

--query roda depois que o dinheiro foi gasto. A flag global --query é JMESPath aplicado à resposta no seu shell. Uma expressão JMESPath como Items[?Year > '2010'] parece um filtro e não é: cada item foi lido, transferido e cobrado antes de o JMESPath vê-lo. O --filter-expression pelo menos impede que os dados sejam transferidos, mas a AWS é explícita ao dizer que ele "is applied after the items have already been read; the process of filtering does not consume any additional read capacity units" (consultado em 2026-07-28). Isso corta dos dois lados, já que significa que o filtro também não as reduz. A única forma de ler menos é uma condição de chave mais estreita ou um índice.

Uma página é 1 MB, independentemente do que você pediu. "A single Query operation will read up to the maximum number of items set (if using the Limit parameter) or a maximum of 1 MB of data" (consultado em 2026-07-28). Uma partição mais larga que isso sempre pagina, e é por isso que a consulta de 30 itens acima nunca foi uma chamada só.

Consultar um índice exige mais uma flag. --index-name troca a condição de chave para as chaves daquele índice; um índice secundário global também rejeita --consistent-read. Veja Consultar um GSI com a AWS CLI.

Faça isso visualmente

Acertar a condição de chave, os dois mapas de placeholders e o loop de paginação em um único comando é toda a dificuldade aqui. O DynamoDB Query Builder gratuito compõe a requisição, incluindo o índice e a paginação, e a emite como um comando de CLI executável.

Para rodar consultas nas suas próprias tabelas — formulário de condição de chave, uma grade que pagina conforme você rola, copiar a requisição de volta como um comando de CLI — baixe o DynoTable.

Guias relacionados

Query vs. Scan — por que query é o padrão certo.
Paginação — LastEvaluatedKey, ExclusiveStartKey e por que Limit não é um tamanho de página.
"Query condition missed key schema element" — a condição de chave nomeia o atributo errado ou pula a chave de partição.
"Query key condition not supported" — um operador que a condição de chave não pode usar, como contains ou uma segunda condição de chave de ordenação.

Referências

Medido em 2026-07-28 com aws-cli/2.36.9 contra o DynamoDB Local (amazon/dynamodb-local) na porta 9000, sobre uma partição de 30 itens de ~60 KB cada. As contagens, tokens e leituras de capacidade acima são saída capturada. O DynamoDB Local calcula a capacidade com as regras de arredondamento documentadas; trate os números absolutos como uma demonstração do formato e meça suas próprias tabelas contra o serviço antes de dimensionar.