Python(boto3)에서의 DynamoDB BatchGetItem

batch_get_item은 단일 요청에서 기본 키로 최대 100개 항목을 가져옵니다(최대 16 MB). boto3 저수준 클라이언트에서는 테이블 → 키의 RequestItems 맵을 전달하며, 배치가 요청한 것의 일부만 정당하게 반환할 수 있으므로 UnprocessedKeys를 반드시 반복 처리해야 합니다.

Code

import time

import boto3

client = boto3.client("dynamodb")

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"}},
        ]
    }
}

items = []
attempt = 0

while request_items:
    response = client.batch_get_item(RequestItems=request_items)
    items.extend(response["Responses"].get("Music", []))

    # A partial result is NOT an error: throttling, a >16 MB response, or an
    # internal failure returns the leftovers in UnprocessedKeys. Retry them
    # with exponential backoff.
    request_items = response["UnprocessedKeys"]
    if request_items:
        attempt += 1
        time.sleep(min(0.1 * 2**attempt, 5))

print(f"Fetched {len(items)} items")

Explanation

RequestItems — 테이블 이름 → {"Keys": [...]}의 맵입니다. 하나의 요청이 여러 테이블에 걸칠 수 있습니다. 모든 키는 DynamoDB JSON({"S": ...}, {"N": ...})으로 된 전체 기본 키(복합 키의 경우 파티션 + 정렬)여야 합니다. 100개를 초과하는 키나 동일한 키가 두 번 있으면 ValidationException이 발생합니다.
Responses — 테이블 이름 → 발견된 항목의 맵입니다. 항목은 특정 순서 없이 반환되며, 존재하지 않는 키는 단순히 나타나지 않습니다 — 키 속성으로 결과를 요청과 매칭하세요.
UnprocessedKeys — 위의 재시도 루프는 선택 사항이 아닙니다. 응답이 16 MB를 넘거나, 처리량이 소진되거나, 파티션 읽기가 1 MB를 넘으면 DynamoDB는 나머지를 여기에 RequestItems 형태로 반환하며, 그대로 다시 넣을 수 있습니다(빈 맵은 완료를 의미 — Python에서 falsy이며, 이것이 while을 끝냅니다). AWS는 재시도 사이에 지수 백오프를 강력히 권장합니다.
일관성 — 배치 읽기는 기본적으로 최종적 일관성을 따릅니다. 강력한 일관성 읽기를 원하면 테이블별로 "ConsistentRead": True를 설정하세요.
테이블별로 일부 속성만 가져오도록 ProjectionExpression(과 ExpressionAttributeNames)도 전달할 수 있습니다.
DynamoDB JSON 대신 네이티브 Python 타입을 선호하시나요? 리소스 API는 평범한 값으로 dynamodb.batch_get_item(...)을 제공하지만, 재시도 계약은 동일합니다 — 어느 쪽이든 UnprocessedKeys를 비우는 것은 여러분의 몫입니다.

Do it visually

DynamoDB JSON 키 맵을 손으로 조립하고 싶지 않으신가요? DynamoDB Expression Builder는 타입 지정 키/값 맵을 만들고 실행 가능한 코드를 복사해 주며, 항목 크기 계산기는 배치가 16 MB 상한에 얼마나 가까워지는지 보여줍니다.

GUI에서 여러 테이블에 걸쳐 항목을 가져오고 검사하려면 — 작성할 재시도 루프 없이 — DynoTable을 다운로드하세요.

DynamoDB BatchGetItem in Node.js — AWS SDK v3를 사용한 동일한 배치 읽기.
DynamoDB BatchGetItem with the AWS CLI — 셸에서 실행하는 동일한 배치 읽기.
DynamoDB GetItem in Python — 이것이 배치하는 단일 항목 읽기.
Batch operations in DynamoDB — 한도, 부분 실패, 그리고 배치가 이득이 되는 경우.
"Too many items requested for the BatchGetItem call" — 하나의 요청에 100개를 초과하는 키.
"Provided list of item keys contains duplicates" — 하나의 배치에 동일한 키가 두 번.

References

Last verified 2026-07-13 against the official AWS documentation linked above.

Python(boto3)에서의 DynamoDB BatchGetItem

Code

Explanation

Do it visually

Related examples

References