Node.js(AWS SDK v3)에서의 DynamoDB BatchGetItem

BatchGetItem은 단일 요청에서 기본 키로 최대 100개 항목을 가져옵니다(최대 16 MB). AWS SDK v3에서는 테이블 → 키의 RequestItems 맵을 담은 BatchGetItemCommand를 보내며, 배치가 요청한 것의 일부만 정당하게 반환할 수 있으므로 UnprocessedKeys를 반드시 반복 처리해야 합니다.

Code

import {BatchGetItemCommand, DynamoDBClient} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({region: 'us-east-1'});

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

let requestItems = {
  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'}}
    ]
  }
};

const items = [];
let attempt = 0;

do {
  const response = await client.send(new BatchGetItemCommand({RequestItems: requestItems}));
  items.push(...(response.Responses?.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.
  requestItems = response.UnprocessedKeys;
  if (requestItems && Object.keys(requestItems).length > 0) {
    attempt += 1;
    await sleep(Math.min(100 * 2 ** attempt, 5000));
  }
} while (requestItems && Object.keys(requestItems).length > 0);

console.log(`Fetched ${items.length} items`);

Explanation

RequestItems — 테이블 이름 → { Keys: [...] }의 맵입니다. 하나의 요청이 여러 테이블에 걸칠 수 있습니다. 모든 키는 전체 기본 키(복합 키의 경우 파티션 + 정렬)여야 합니다. 100개를 초과하는 키나 동일한 키가 두 번 있으면 ValidationException으로 실패합니다.
Responses — 테이블 이름 → 발견된 항목의 맵입니다. 항목은 특정 순서 없이 반환되며, 존재하지 않는 키는 단순히 나타나지 않습니다 — 키 속성으로 결과를 요청과 매칭하세요.
UnprocessedKeys — 위의 재시도 루프는 선택 사항이 아닙니다. 응답이 16 MB를 넘거나, 처리량이 소진되거나, 파티션 읽기가 1 MB를 넘으면 DynamoDB는 나머지를 여기에 RequestItems 형태로 반환하며, 그대로 다시 넣을 수 있습니다. AWS는 재시도 사이에 지수 백오프를 강력히 권장합니다 — 즉시 재시도하면 같은 스로틀에 다시 걸리기 쉽습니다.
일관성 — 배치 읽기는 기본적으로 최종적 일관성을 따릅니다. 강력한 일관성 읽기를 원하면 테이블별로 ConsistentRead: true를 설정하세요.
테이블별로 일부 속성만 가져오도록 ProjectionExpression(과 ExpressionAttributeNames)도 전달할 수 있습니다.
BatchGetItem은 서버 측에서 항목을 병렬로 가져올 수 있습니다 — 왕복은 절약하지만 읽기 용량은 아닙니다: DynamoDB는 배치의 각 항목을 개별 GetItem으로 청구합니다.

Do it visually

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

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

DynamoDB BatchGetItem in Python — boto3를 사용한 동일한 배치 읽기.
DynamoDB BatchGetItem with the AWS CLI — 셸에서 실행하는 동일한 배치 읽기.
DynamoDB GetItem in Node.js — 이것이 배치하는 단일 항목 읽기.
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.

Node.js(AWS SDK v3)에서의 DynamoDB BatchGetItem

Code

Explanation

Do it visually

Related examples

References