AWS CLI를 사용한 DynamoDB BatchWriteItem

aws dynamodb batch-write-item은 단일 명령으로 최대 25개 항목을 put하거나 delete합니다(총 16 MB, 항목당 400 KB). 쓰기는 DynamoDB JSON으로 된 테이블 → PutRequest/DeleteRequest 항목의 맵으로 --request-items에 들어가며, 배치 전체는 원자적이지 않으므로 출력에서 UnprocessedItems를 확인해야 합니다.

Code

aws dynamodb batch-write-item \
  --request-items '{
    "Music": [
      {"PutRequest": {"Item": {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}, "AlbumTitle": {"S": "Danzon"}, "Year": {"N": "1994"}}}},
      {"PutRequest": {"Item": {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "A Mis Abuelos"}, "AlbumTitle": {"S": "Danzon"}, "Year": {"N": "1994"}}}},
      {"DeleteRequest": {"Key": {"Artist": {"S": "Ella Fitzgerald"}, "SongTitle": {"S": "Misty"}}}}
    ]
  }'

모든 것이 처리되면 출력의 남은 맵은 비어 있습니다:

{
    "UnprocessedItems": {}
}

Explanation

--request-items — 테이블 이름 → 최대 25개의 PutRequest/DeleteRequest 항목 배열의 맵입니다(하나의 명령이 여러 테이블에 걸칠 수 있습니다). 각 PutRequest.Item은 전체 기본 키가 필요하며, 각 DeleteRequest.Key는 키만 필요합니다. 값은 DynamoDB JSON입니다 — 숫자는 N 아래에서 문자열입니다.
트랜잭션이 아님 — 각 put/delete는 개별적으로 원자적이지만, 배치 전체는 그렇지 않습니다. 전부 아니면 전무가 필요한가요? transact-write-items를 사용하세요.
UnprocessedItems — CLI는 부분 배치를 자동 재시도하지 않습니다. 맵이 비어 있지 않으면(보통 스로틀링이 원인), 그 정확한 맵을 --request-items로 하여 명령을 다시 실행하고 — 이미 올바른 형태입니다 — 시도 사이에 백오프하세요.
업데이트 없음, 조건 없음 — batch-write-item은 update-item, --condition-expression, --return-values를 표현할 수 없습니다. 기존 키에 대한 put은 항목 전체를 조용히 교체합니다. 중복 키, 동일 항목에 대한 put+delete, 25개 초과 요청, 400 KB 초과 항목, 또는 총 16 MB 초과는 각각 DynamoDB가 배치 전체를 거부하게 만듭니다.
팁: 맵을 파일에 두고 --request-items file://writes.json으로 전달하세요 — 25개 항목을 인라인으로 셸 인용하는 것은 고역입니다.

Do it visually

셸 인용부호 안에서 중첩된 DynamoDB JSON을 손으로 작성하는 것은 오류가 나기 쉽습니다. DynamoDB Expression Builder는 타입 지정 값 맵을 만들고 바로 실행 가능한 CLI 명령을 복사해 주며, 항목 크기 계산기는 각 항목을 400 KB 상한에 대해 확인합니다.

GUI에서 항목을 대량으로 추가, 편집, 삭제하려면 — JSON 이스케이프 대신 CSV/JSON 가져오기로 — DynoTable을 다운로드하세요.

DynamoDB BatchWriteItem in Node.js — AWS SDK v3를 사용한 동일한 배치 쓰기.
DynamoDB batch write in Python — boto3의 batch_writer()가 재시도 루프를 대신 처리합니다.
DynamoDB PutItem with the AWS CLI — 이것이 배치하는 단일 항목 쓰기.
Batch operations in DynamoDB — 한도, 부분 실패, 그리고 배치가 이득이 되는 경우.
"Too many items requested for the BatchWriteItem call" — 하나의 배치에 25개를 초과하는 put/delete 요청.
"Provided list of item keys contains duplicates" — 하나의 배치에서 동일한 키를 건드리는 두 개의 요청.

References

Last verified 2026-07-13 against the official AWS documentation linked above.

AWS CLI를 사용한 DynamoDB BatchWriteItem

Code

Explanation

Do it visually

Related examples

References