DynamoDB 항목 기반 작업: GetItem, PutItem, UpdateItem, DeleteItem

DynamoDB의 API는 세 부류로 나뉩니다: 기본 키로 단일 항목을 다루는 항목 기반 작업, 한 파티션 안의 범위를 읽는 Query, 그리고 전부를 읽는 Scan입니다. 이 가이드는 첫 번째 부류 — 여러분이 가장 많이 쓰는 네 작업: GetItem, PutItem, UpdateItem, DeleteItem을 다룹니다. 이들은 DynamoDB가 제공하는 가장 저렴하고 빠른 호출이며, 그 차이(특히 Put 대 Update)를 제대로 이해하면 한 부류의 우발적 데이터 손실 버그를 막을 수 있습니다.

DynamoDB의 항목 기반 작업이란?

DynamoDB의 항목 기반 작업은 전체 기본 키로 단일 항목을 다루는 네 가지 호출입니다: GetItem은 항목을 읽고, PutItem은 항목을 생성하거나 통째로 교체하며, UpdateItem은 특정 속성을 제자리에서 수정하고, DeleteItem은 항목을 제거합니다. 각각이 정확히 하나의 항목만 다루므로 가장 빠르고 저렴한 호출이며 — 여러 항목을 읽는 Query 및 Scan과 다릅니다.

GetItem — 전체 기본 키로 항목 하나를 읽습니다.
PutItem — 항목 하나를 생성하거나 통째로 교체합니다.
UpdateItem — 항목 하나의 특정 속성을 제자리에서 생성하거나 수정합니다.
DeleteItem — 전체 기본 키로 항목 하나를 제거합니다.
네 작업 모두 완전한 기본 키가 필요합니다(파티션 키, 그리고 테이블에 정렬 키가 있다면 정렬 키까지) — 정확히 하나의 항목을 지목합니다.
PutItem은 항목 전체를 덮어쓰고, UpdateItem은 외과적입니다 — 둘을 혼동하면 속성이 조용히 사라집니다.

결정적 특징: 항목 하나, 전체 키

모든 항목 기반 작업은 완전한 기본 키로 단일 항목을 지목합니다. 그것이 이들을 빠르고 저렴하게 만드는 요인입니다 — DynamoDB가 파티션 키를 해싱해 곧장 항목으로 가고, 끝입니다. 필터링도, 스캔도 없습니다. 전체 키를 모른다면 이들은 맞는 도구가 아닙니다. 그건 Query와 Scan의 몫입니다.

USER#<id>로 키잉된 사용자 계정을 운영한다고 합시다:

PK: USER#204   email, displayName, plan, createdAt

USER#204에 대한 GetItem → 그 사용자를, 곧장.
USER#204에 대한 DeleteItem → 그 사용자를 제거.

둘 다 정확한 키가 필요합니다. 키가 없으면 항목 기반 작업도 없습니다.

`PutItem` 대 `UpdateItem` — 발목 잡는 그것

내재화할 가치가 있는 구분입니다:

PutItem은 항목 전체를 씁니다. USER#204가 이미 존재하는데 {email, displayName}만으로 PutItem을 하면, 기존 plan과 createdAt 속성은 사라집니다 — put은 항목 전체를 교체할 뿐, 병합하지 않습니다.
UpdateItem은 여러분이 지정한 것만 바꿉니다. SET email = …을 쓰는 UpdateItem은 다른 모든 속성을 건드리지 않고, 항목이 없었다면 생성합니다(upsert).

경험 법칙: 기존 항목을 바꾸려면 UpdateItem에 손을 뻗으세요. PutItem은 진정 "이 항목을 완전한 새 상태로 쓴다"는 뜻일 때만 쓰세요. PutItem과 UpdateItem 모두 조건 표현식을 받으므로 쓰기를 조건부로 만들 수 있습니다("아직 존재하지 않을 때만").