AWS CLI での DynamoDB Scan
aws dynamodb scan は自動でページ送りします。便利ですが、被害を判断するために使うはずのただ 1 つの数字が既定で誤っている、ということでもあります。この操作をそもそも避けるべき場面は Query と Scan の比較を参照してください。
コード
aws dynamodb scan \
--table-name 'Music' \
--filter-expression '#filter0 >= :filterValue0' \
--expression-attribute-names '{"#filter0":"Year"}' \
--expression-attribute-values '{":filterValue0":{"N":"2010"}}'--return-consumed-capacity はスキャンではなく 1 ページ分を報告する
用意したデータは約 3.9 KB の曲 600 件で、そのうち一致するのは 8 件です。上のコマンドに --return-consumed-capacity TOTAL を足すと、CLI はこう出力します。
{ "Count": 8, "ScannedCount": 600, "CU": 128.5 }このスキャンが実際に要したのは 3 ページにわたる 284.5 読み取りユニットです。Count と ScannedCount は 3 ページ分が合計された一方、ConsumedCapacity は 1 ページ目のものが取られ、残りは捨てられました。これはバグというより宣言されたルールです。botocore の DynamoDB ページネータ設定は、Count と ScannedCount を結果キーとして、ConsumedCapacity を非集計キーとして挙げています。
分かりやすい証拠は、仕事量が変わっていないのに数字が動くことです。同じテーブル、読んだのは同じ 600 件、フラグを 1 つ足しただけです。
--page-size 50 -> { "Count": 8, "ScannedCount": 600, "CU": 24.0 }CLI のスキャンからテーブルのサイジングをするなら、--page-size と --starting-token で自分でページを合計するか、CloudWatch からキャパシティを読んでください。
--max-items はスキャンを止めない
--max-items 3 は安上がりなサンプリングのように読めます。違います。
--max-items 3 -> { "Count": 8, "ScannedCount": 600 }CLI は必要な件数の一致が集まるまでページを要求し続けました。選択性の高いフィルタでは、それはテーブル全体を意味します。その後、出力するリストを切り詰めただけです。CLI 自身の再開トークンがそれを明言しています。
{"ExclusiveStartKey": {"Artist": {"S": "Arturo Sandoval"},
"SongTitle": {"S": "Cubano Chant 0541"}}, "boto_truncate_amount": 3}boto_truncate_amount はクライアント側のカウンタです。DynamoDB が読む量を制限するには --page-size を使ってください。これは基盤となる各リクエストに API の Limit を設定します。再開は --starting-token で行います。
aws dynamodb scan \
--table-name 'Music' \
--page-size 500 \
--max-items 100 \
--starting-token "$NEXT_TOKEN"2026-07-28 に、aws-cli/2.36.9 で DynamoDB Local（amazon/dynamodb-local）に対して測定しました。上記の JSON は CLI 自身の出力を、幅の都合で --query によって整形したものです。
解説
--filter-expressionは読み取りの後に走る ので、出力は小さくなっても請求は小さくなりません。Yearは予約語なので、#filter0が--expression-attribute-namesを通じてYearのエイリアスになっています。--expression-attribute-valuesは数値を二重にクォートすることを求めます。JSON 全体を囲むシェルのクォートと、値そのものを JSON の文字列にすることです。内側のクォートを落とすと DynamoDB には届きません。CLI がローカルでInvalid type for parameter ExpressionAttributeValues.:v.N, value: 2010, type: <class 'int'>, valid types: <class 'str'>と拒否します。- API 呼び出しを変えるフラグは
--page-sizeです。これは基盤となる各リクエストのLimitになり、1 ページあたりに評価されるアイテム数を抑えます。ページネーション一族の残り（--max-items、--starting-token）は、CLI が自分の出力を管理しているだけです。 - 並列スキャン はワーカーごとに
--segment N --total-segments Mを必要とし、各ワーカーが自分の--starting-tokenを持ちます。買えるのは実時間であって、キャパシティではありません。
ビジュアルに行う
DynamoDB 式ビルダーは、フィルタと 2 つの JSON マップをシェル用にエスケープ済みで出力するので、DynamoDB に届く前に CLI の式を失敗させるクォーティングの層を取り除けます。
テーブルを GUI で、フィルタとページ送りの効いたグリッドとともに探索するには、端末から手探りでスキャンする代わりに DynoTable をダウンロードしてください。
関連ガイド
- Query と Scan の比較 — （まれに）
scanが正当化される場面。 - DynamoDB の Scan が遅くて高くつくのはなぜ？ — コストモデルと、その回避方法。
- DynamoDB ProvisionedThroughputExceededException — フルテーブルスキャンがプロビジョニング済みテーブルのキャパシティに何をするか。
- DynamoDB ThrottlingException — もう一方のスロットリングと、指数バックオフによる対処。