AWS CLI로 하는 DynamoDB Scan
aws dynamodb scan은 자동으로 페이지를 넘깁니다. 편리하다는 뜻이자, 피해 규모를 판단하는 데 쓸 그 하나의 숫자가 기본적으로 틀렸다는 뜻이기도 합니다. 이 작업을 아예 피해야 할 때는 Query vs. 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는 스캔이 아니라 한 페이지를 보고합니다
픽스처는 각각 대략 3.9 KB인 곡 600개이고 그중 8개가 조건에 맞습니다. 위 명령에 --return-consumed-capacity TOTAL을 붙이면 CLI는 이렇게 출력합니다:
{ "Count": 8, "ScannedCount": 600, "CU": 128.5 }이 스캔이 실제로 쓴 것은 세 페이지에 걸쳐 284.5 읽기 단위입니다. Count와 ScannedCount는 세 페이지 모두 합산되었지만, ConsumedCapacity는 첫 페이지 것만 취하고 나머지는 버려졌습니다. 이것은 버그라기보다 선언된 규칙입니다 — botocore의 DynamoDB 페이지네이터 설정은 Count와 ScannedCount를 결과 키로, ConsumedCapacity를 비집계 키로 나열합니다.
작업량은 그대로인데 수치가 움직인다는 것이 단서입니다. 같은 테이블, 같은 600개 항목 읽기, 플래그 하나 추가:
--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가 읽는 양을 제한하려면 각 하위 요청에 API의 Limit을 설정하는 --page-size를 쓰고, --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이 되어 페이지당 평가되는 항목 수를 제한합니다. 페이지네이션 계열의 나머지(--max-items,--starting-token)는 CLI가 자기 출력을 관리하는 것입니다. - 병렬 스캔은 워커마다
--segment N --total-segments M이 필요하며, 각 워커가 자기--starting-token을 유지합니다. 이것이 사는 것은 벽시계 시간이지 용량이 아닙니다.
시각적으로 해보기
DynamoDB Expression Builder는 필터와 두 JSON 맵을 셸에 맞춰 이미 이스케이프된 상태로 내보내므로, DynamoDB가 보기도 전에 CLI 표현식을 실패하게 만드는 따옴표 계층을 없애 줍니다.
터미널에서 눈감고 스캔하는 대신, 필터가 걸리고 페이지가 나뉜 그리드로 GUI에서 테이블을 탐색하려면 DynoTable을 다운로드하세요.
관련 가이드
- Query vs. Scan — (드물게)
scan이 정당한 때. - DynamoDB Scan은 왜 느리고 비쌀까? — 비용 모델과 회피법.
- DynamoDB ProvisionedThroughputExceededException — 전체 테이블 스캔이 프로비저닝된 테이블의 용량에 하는 일.
- DynamoDB ThrottlingException — 또 다른 스로틀링과 지수 백오프가 그것을 다루는 방식.