Node.js (AWS SDK v3) での DynamoDB BatchGetItem

BatchGetItem は、1回のリクエストでプライマリキーによって最大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: [...] } のマップ。1回のリクエストが複数のテーブルにまたがることもできます。各キーは完全なプライマリキー（複合キーならパーティション + ソート）である必要があります。100個を超えるキー、または同じキーが2回あると 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 は型付きのキー/値マップを構築して実行可能なコードをコピーし、item size calculator はバッチが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" — 1つのリクエストに100個を超えるキー。
"Provided list of item keys contains duplicates" — 1つのバッチに同じキーが2回。

References

最終検証日 2026-07-13、上記にリンクした公式 AWS ドキュメントに照らして確認しました。

Node.js (AWS SDK v3) での DynamoDB BatchGetItem

Code

Explanation

Do it visually

Related examples

References