Node.js(AWS SDK v3)의 DynamoDB GetItem

AWS SDK v3는 항목 하나를 읽는 방법을 두 가지 줍니다. 와이어 형식({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이 그냥 없을 뿐이고 호출은 정상적으로 resolve됩니다. 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 다운로드.

참고 자료

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

Node.js(AWS SDK v3)의 DynamoDB GetItem

코드

설명

시각적으로 해보기

관련 가이드

참고 자료