AWS CLI를 사용한 DynamoDB BatchGetItem

aws dynamodb batch-get-item은 한 번의 명령으로 기본 키 기준 항목을 최대 100개 가져옵니다. 명령줄에서 query나 scan과 갈리는 지점은 두 가지입니다. 키가 셸 인용을 뚫고 살아남아야 하는 중첩된 DynamoDB JSON이라는 점, 그리고 CLI가 UnprocessedKeys를 대신 비워 주지 않는다는 점입니다. 한도와 부분 결과 규칙은 DynamoDB 배치 작업에 있습니다.

코드

aws dynamodb batch-get-item \
  --request-items '{
    "Music": {
      "Keys": [
        {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}},
        {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "A Mis Abuelos"}},
        {"Artist": {"S": "Ella Fitzgerald"}, "SongTitle": {"S": "Misty"}}
      ]
    }
  }'

축약하면, 출력은 각 테이블을 찾아낸 항목과 남은 키에 대응시킵니다. 그대로 옮긴 전체 실행 결과는 이 페이지 아래쪽에 있습니다:

{
    "Responses": {
        "Music": [
            {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}, ...}
        ]
    },
    "UnprocessedKeys": {}
}

설명

CLI에는 이 명령을 위한 페이지네이션 장치가 없습니다. aws dynamodb query help는 --starting-token, --max-items, --page-size를 나열하지만, aws dynamodb batch-get-item help는 셋 중 아무것도 나열하지 않습니다. UnprocessedKeys는 페이지네이션 토큰이 아니고 CLI는 이 호출을 일회성으로 취급하므로, 남은 키를 비우는 일은 플래그가 아니라 직접 짜는 셸 루프입니다.
남은 키 맵은 이미 입력 형식 그대로입니다. 비어 있지 않은 UnprocessedKeys는 형태를 바꾸지 않고 곧장 --request-items로 되돌려 넣을 수 있으며, 그 덕분에 bash의 while 루프가 참을 만해집니다. 시도 사이에는 sleep을 두세요. 즉시 다시 실행하면 스로틀링된 같은 파티션에 부딪힙니다.
ProjectionExpression과 ConsistentRead는 테이블별 객체 안, "Keys" 옆에 들어갑니다. 이를 --request-items의 최상위에 두는 것이 여기서 가장 흔한 형태 오류입니다.
맵은 파일에 두세요. --request-items file://keys.json은 셸 인용을 통째로 우회하며, 키가 몇 개를 넘어가면 유일하게 온전한 선택지입니다. 동시에 100개 키 상한에 눈치채지 못한 채 도달하게 되는 경로이기도 합니다.

명령이 실제로 출력하는 것

위 코드 블록을 세 곡이 모두 들어 있는 DynamoDB Local 3.3.0에 대해 그대로 실행한 결과입니다(aws-cli/2.36.9):

{
    "Responses": {
        "Music": [
            {
                "Artist": {"S": "Arturo Sandoval"},
                "AlbumTitle": {"S": "Danzon"},
                "Year": {"N": "1994"},
                "SongTitle": {"S": "A Mis Abuelos"}
            },
            {
                "Artist": {"S": "Ella Fitzgerald"},
                "AlbumTitle": {"S": "Ella in Berlin"},
                "Year": {"N": "1960"},
                "SongTitle": {"S": "Misty"}
            },
            {
                "Artist": {"S": "Arturo Sandoval"},
                "AlbumTitle": {"S": "Danzon"},
                "Year": {"N": "1994"},
                "SongTitle": {"S": "Cubano Chant"}
            }
        ]
    },
    "UnprocessedKeys": {}
}

(속성 맵은 각각 한 줄로 접었고, 나머지는 출력된 그대로입니다.) 명령은 Cubano Chant를 첫 번째로 요청했지만 마지막으로 받았습니다. 응답에서 위치에 의미가 있는 것은 아무것도 없으므로, .Responses.Music[0]을 인덱싱하는 jq 표현식은 서비스가 마침 먼저 반환하기로 한 항목을 읽는 셈입니다. 대신 키 속성으로 필터링하세요.

곧바로 거부되는 요청이 두 가지 있으며, stderr로 출력되고 종료 상태는 254입니다:

aws: [ERROR]: An error occurred (ValidationException) when calling the BatchGetItem operation: Provided list of item keys contains duplicates
aws: [ERROR]: An error occurred (ValidationException) when calling the BatchGetItem operation: Too many items requested for the BatchGetItem call

aws: [ERROR]: 접두사는 CLI v2 래퍼가 붙인 것이고, 그 뒤의 텍스트는 서비스 자체의 메시지입니다. 0이 아닌 종료 상태를 모두 스로틀링으로 취급하는 재시도 루프는 이 둘 중 어느 쪽에서도 영원히 돌게 되므로, 백오프하기 전에 메시지로 분기하세요.

작은따옴표 안에 그 중첩 JSON을 손으로 쓰는 것이 오류 대부분의 출처입니다. DynamoDB Expression Builder는 타입이 지정된 키 맵을 조립하고 바로 실행할 수 있는 명령을 복사해 주므로, 최소한 인용 문제는 용의선상에서 지울 수 있습니다.

JSON을 오가지 않고 키 묶음을 읽어 항목을 확인하려면 DynoTable을 다운로드하세요.

참고 자료

위에 링크된 공식 AWS 문서를 기준으로 2026-07-28에 마지막으로 검증했습니다.

AWS CLI를 사용한 DynamoDB BatchGetItem

코드

설명

명령이 실제로 출력하는 것

관련 예제

참고 자료