Scan DynamoDB avec l'AWS CLI

aws dynamodb scan pagine automatiquement, ce qui est pratique et signifie que le seul chiffre qui te servirait à juger des dégâts est faux par défaut. Voir Query vs. Scan pour savoir quand éviter complètement l'opération.

Code

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

--return-consumed-capacity rapporte une page, pas le scan

Le jeu de test compte 600 morceaux d'environ 3,9 Ko chacun, dont 8 correspondent. Ajoute --return-consumed-capacity TOTAL à cette commande et la CLI affiche :

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

Le scan a réellement coûté 284,5 unités de lecture sur trois pages. Count et ScannedCount ont été additionnés sur les trois ; ConsumedCapacity a été pris sur la première et le reste jeté. Ce n'est pas tant un bug qu'une règle déclarée — la configuration du paginateur DynamoDB de botocore liste Count et ScannedCount comme clés de résultat et ConsumedCapacity comme clé non agrégée.

Le signe qui trahit, c'est que le chiffre bouge alors que le travail, lui, ne bouge pas. Même table, mêmes 600 éléments lus, un flag de plus :

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

Si tu dimensionnes une table à partir d'un scan CLI, additionne les pages toi-même avec --page-size plus --starting-token, ou lis la capacité dans CloudWatch.

--max-items n'arrête pas le scan

--max-items 3 a tout l'air d'un échantillon bon marché. Il n'en est rien :

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

La CLI a continué à demander des pages jusqu'à obtenir assez de correspondances — ce qui, avec un filtre sélectif, a voulu dire la table entière — puis a tronqué la liste affichée. Son propre token de reprise le dit tout haut :

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

boto_truncate_amount est un compteur côté client. Pour borner ce que DynamoDB lit, utilise --page-size, qui fixe le Limit de l'API sur chaque requête sous-jacente, et reprends avec --starting-token :

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

Mesuré le 2026-07-28 sur DynamoDB Local (amazon/dynamodb-local) avec aws-cli/2.36.9. Le JSON ci-dessus est la sortie de la CLI elle-même, remise en forme par --query pour la largeur.

Explication

• --filter-expression s'exécute après la lecture : il réduit la sortie, pas la facture. #filter0 fait alias sur Year via --expression-attribute-names parce que Year est un mot réservé.
• --expression-attribute-values veut le nombre entre guillemets deux fois : les guillemets du shell autour du JSON, et la valeur en tant que chaîne JSON. Retirer les guillemets intérieurs n'atteint jamais DynamoDB — la CLI le rejette localement avec Invalid type for parameter ExpressionAttributeValues.:v.N, value: 2010, type: <class 'int'>, valid types: <class 'str'>.
• --page-size est le flag qui change l'appel d'API. Il devient le Limit de chaque requête sous-jacente et plafonne les éléments évalués par page. Le reste de la famille pagination (--max-items, --starting-token) n'est que la CLI gérant sa propre sortie.
• Le scan parallèle demande --segment N --total-segments M par worker, et chaque worker garde son propre --starting-token. Il t'achète du temps d'horloge, pas de la capacité.

Le faire visuellement

Le DynamoDB Expression Builder émet le filtre et les deux maps JSON déjà échappés pour le shell, ce qui supprime la couche d'échappement qui fait échouer les expressions CLI avant même que DynamoDB ne les voie.

Pour explorer tes tables dans un GUI, avec des grilles filtrées et paginées, télécharge DynoTable plutôt que de scanner à l'aveugle depuis le terminal.

Guides liés

• Query vs. Scan — quand (rarement) un scan se justifie.
• Pourquoi mon Scan DynamoDB est-il lent et coûteux ? — le modèle de coût et comment l'éviter.
• DynamoDB ProvisionedThroughputExceededException — ce qu'un scan de table complet fait à la capacité d'une table provisionnée.
• DynamoDB ThrottlingException — l'autre throttle, et comment le backoff exponentiel le gère.

Références

• 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