Node.js（AWS SDK v3）での DynamoDB GetItem

AWS SDK v3 では、1 件のアイテムを読む方法が 2 つあります。ワイヤ形式（{S: '...'}）を話す DynamoDBClient 上の GetItemCommand か、素の JavaScript を受け取って返す DynamoDBDocumentClient 上の GetCommand です。

この例では低レベルクライアントを使います。あの型ラッパーこそ、属性値のエンコーディングがワイヤ上で実際にどう見えるかであり、エラーメッセージが引用してくるものです。いずれにせよ、リクエストには完全なプライマリキーが必要です。

コード

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

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

const command = new GetItemCommand({
  TableName: 'Music',
  Key: {
    Artist: {S: 'Arturo Sandoval'},
    SongTitle: {S: 'Cubano Chant'}
  },
  ProjectionExpression: '#proj0, #proj1, #proj2, #proj3',
  ExpressionAttributeNames: {
    '#proj0': 'Artist',
    '#proj1': 'SongTitle',
    '#proj2': 'AlbumTitle',
    '#proj3': 'Year'
  }
});

const response = await client.send(command);

if (!response.Item) {
  console.log('Item not found');
} else {
  console.log(response.Item);
}

解説

client.getItem() ではなく send(command) です — DynamoDBClient が公開しているのは send だけです。SDK v2 スタイルの呼び出しが欲しければ、同じパッケージの集約された DynamoDB クラスには getItem メソッドがあります。ただし、すべてのコマンドをバンドルに引きずり込むという代償を伴います。
ヒットしない場合は undefined であり、エラーではありません — response.Item が単に存在せず、呼び出しは解決します。response.$metadata は常に届くので、レスポンス自体の真偽値からは何も分かりません。
unmarshall は数値の型を大きさで選びます — 安全な整数の範囲に収まる {N: …} は number として返り、範囲外は BigInt になり、大きな非整数は can't be converted to BigInt を送出します。@aws-sdk/util-dynamodb の unmarshall に {wrapNumbers: true} を渡せば、すべての数値が代わりに NumberValue として届くので、変換は自分で決められます。
#proj の別名は飾りではありません — Year は AWS の予約語リストに載っているので、それを直接名指しする ProjectionExpression は拒否されます。上のようにすべての名前に別名を付けるのが安全なデフォルトです。これが削るのはレスポンスであって、読み取りコストではありません（理由）。
ConsumedCapacity はオプトインです — ReturnConsumedCapacity: 'TOTAL' を足すと、この読み取りが実際にいくらかかったかがレスポンスに報告されます。4 KB 未満のアイテムの結果整合性のある読み取りで 0.5 キャパシティユニット、ConsistentRead: true を足すと 1.0 です（トレードオフ）。
クライアントは巻き上げましょう — DynamoDBClient はモジュールスコープで一度だけ構築します。リクエストごとに、あるいは Lambda ハンドラーの中で作ると、呼び出しのたびにコネクションプールと解決済みの認証情報を捨てることになります。

ビジュアルに行う

DynoTable はアイテムを属性値のマップではなく普通の行として表示し、グリッドの背後にあるクエリを、そのまま実行できる SDK v3 のプログラムとしてエクスポートします。DynoTable をダウンロードしてください。

参考資料

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

Node.js（AWS SDK v3）での DynamoDB GetItem

コード

解説

ビジュアルに行う

関連ガイド

参考資料