Scan do DynamoDB com a AWS CLI

aws dynamodb scan pagina automaticamente, o que é conveniente e significa que o único número que você usaria para avaliar o estrago está errado por padrão. Veja Query vs. Scan para saber quando evitar a operação por completo.

Código

aws dynamodb scan \
  --table-name 'Music' \
  --filter-expression '#filter0 >= :filterValue0' \
  --expression-attribute-names '{"#filter0":"Year"}' \
  --expression-attribute-values '{":filterValue0":{"N":"2010"}}'

--return-consumed-capacity reporta uma página, não o scan

A fixture tem 600 músicas de aproximadamente 3,9 KB cada, das quais 8 dão match. Adicione --return-consumed-capacity TOTAL àquele comando e a CLI imprime:

{ "Count": 8, "ScannedCount": 600, "CU": 128.5 }

O scan realmente custou 284,5 unidades de leitura ao longo de três páginas. Count e ScannedCount foram somados nas três; o ConsumedCapacity foi pego da primeira e o resto, descartado. Isso não é bem um bug, e sim uma regra declarada — a configuração do paginador de DynamoDB do botocore lista Count e ScannedCount como result keys e ConsumedCapacity como uma non-aggregate key.

O indício é que o número muda quando o trabalho não muda. Mesma tabela, os mesmos 600 itens lidos, uma flag a mais:

--page-size 50  ->  { "Count": 8, "ScannedCount": 600, "CU": 24.0 }

Se você está dimensionando uma tabela a partir de um scan pela CLI, some as páginas você mesmo com --page-size mais --starting-token, ou leia a capacidade no CloudWatch.

--max-items não interrompe o scan

--max-items 3 parece uma amostra barata. Não é:

--max-items 3  ->  { "Count": 8, "ScannedCount": 600 }

A CLI continuou pedindo páginas até ter matches suficientes, o que, com um filtro seletivo, significou a tabela inteira, e só então truncou a lista impressa. O próprio token de retomada dela diz isso em alto e bom som:

{"ExclusiveStartKey": {"Artist": {"S": "Arturo Sandoval"},
 "SongTitle": {"S": "Cubano Chant 0541"}}, "boto_truncate_amount": 3}

boto_truncate_amount é um contador do lado do cliente. Para limitar o que o DynamoDB lê, use --page-size, que define o Limit da API em cada requisição subjacente, e retome com --starting-token:

aws dynamodb scan \
  --table-name 'Music' \
  --page-size 500 \
  --max-items 100 \
  --starting-token "$NEXT_TOKEN"

Medido em 2026-07-28 contra o DynamoDB Local (amazon/dynamodb-local) com aws-cli/2.36.9. O JSON acima é a saída da própria CLI, remodelada com --query por questão de largura.

Explicação

• --filter-expression roda depois da leitura, então ele encolhe a saída e não a conta. #filter0 faz alias de Year através de --expression-attribute-names porque Year é uma palavra reservada.
• --expression-attribute-values quer o número entre aspas duas vezes: aspas de shell em volta do JSON, e o valor como uma string JSON. Tirar as aspas internas nunca chega ao DynamoDB — a CLI rejeita localmente com Invalid type for parameter ExpressionAttributeValues.:v.N, value: 2010, type: <class 'int'>, valid types: <class 'str'>.
• --page-size é a flag que muda a chamada de API. Ela vira Limit em cada requisição subjacente, limitando os itens avaliados por página. O resto da família de paginação (--max-items, --starting-token) é a CLI gerenciando a própria saída.
• O scan paralelo precisa de --segment N --total-segments M por worker, e cada worker mantém seu próprio --starting-token. Ele compra tempo de relógio, não capacidade.

Faça isso visualmente

O DynamoDB Expression Builder emite o filtro e os dois mapas JSON já escapados para o shell, o que elimina a camada de aspas que faz as expressões de CLI falharem antes mesmo de o DynamoDB vê-las.

Para explorar tabelas em uma GUI, com grades filtradas e paginadas, baixe o DynoTable em vez de escanear às cegas pelo terminal.

Guias relacionados

• Query vs. Scan — quando (raramente) um scan se justifica.
• Por que meu Scan do DynamoDB é lento e caro? — o modelo de custo e como evitá-lo.
• DynamoDB ProvisionedThroughputExceededException — o que um scan de tabela inteira faz com a capacidade de uma tabela provisionada.
• DynamoDB ThrottlingException — o outro throttle, e como o backoff exponencial lida com ele.

Referências

• Scan — Amazon DynamoDB API Reference
• scan — AWS CLI Command Reference
• Using the pagination options in the AWS CLI — AWS CLI User Guide
• Scanning tables — Amazon DynamoDB Developer Guide