AWS CLI를 사용한 DynamoDB BatchWriteItem

aws dynamodb batch-write-item은 한 번의 명령으로 항목을 최대 25개 넣거나 삭제합니다. 셸에서 쓸 때는 SDK가 완화해 주는 날카로운 부분이 둘 드러납니다. 모든 값이 정확히 인용해야 하는 DynamoDB JSON이라는 점, 그리고 CLI에 UnprocessedItems를 비우는 장치가 전혀 없다는 점입니다. 한도와 부분 실패 모델은 DynamoDB 배치 작업에 있습니다.

코드

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"}}}}
    ]
  }'

DynamoDB Local 3.3.0에 대해 실행하면 다음이 전부입니다:

{
    "UnprocessedItems": {}
}

설명

비어 있는 잔여 맵이 얻을 수 있는 유일한 성공 신호입니다. 이 명령은 UnprocessedItems만 출력하므로, 종료 상태만 확인하는 스크립트는 절반만 써진 배치를 성공으로 부릅니다. 맵을 파싱하세요. jq -e '.UnprocessedItems | length == 0'이 검사의 전부입니다.
그것을 비워 주는 플래그는 없습니다. aws dynamodb query help는 --starting-token, --max-items, --page-size를 제공하지만, aws dynamodb batch-write-item help는 그중 아무것도 제공하지 않습니다. UnprocessedItems가 페이지네이션 커서가 아니기 때문입니다. 다시 넣는 일은 sleep이 들어간 셸 루프이며, 그 값은 이미 --request-items 형태입니다.
--condition-expression과 --return-values는 여기서 받아들여지지 않으며, 이는 CLI가 아니라 API의 문제입니다. 개별 put 및 delete 요청에는 조건을 붙일 수 없습니다. 모든 PutRequest는 저장된 항목 전체를 대체하므로, 일부만 담은 페이로드로 만든 배치는 빠뜨린 속성을 지웁니다.
인라인 JSON 대신 file://을 쓰세요. --request-items file://writes.json은 셸 인용을 잘못될 수 있는 것들의 목록에서 제거해 주는데, 이 명령에서 잘못되는 것 대부분이 인용이라는 점에서 중요합니다.
잘못된 항목 하나가 25개 전부를 날립니다. 없는 테이블, 스키마와 맞지 않는 키, 400 KB를 넘는 항목, 총 16 MB 초과, 2048바이트를 넘는 파티션 키나 1024바이트를 넘는 정렬 키는 각각 문제의 항목만이 아니라 배치 전체를 거부시킵니다.

명령이 출력하는 것, 거부 사례까지

위 코드 블록에 --return-consumed-capacity TOTAL을 추가하면 DynamoDB Local 3.3.0은 이렇게 답합니다:

{
    "UnprocessedItems": {},
    "ConsumedCapacity": [
        {
            "TableName": "Music",
            "CapacityUnits": 3.0
        }
    ]
}

put 두 개와 delete 하나에 3단위입니다. 배치가 사 온 것은 왕복 한 번이지 할인이 아닙니다. 각 항목은 그것이 대신하는 개별 PutItem이나 DeleteItem으로, 1 KB 단위로 올림되어 과금됩니다.

Ella Fitzgerald / Misty가 이미 사라진 뒤 삭제를 한 번 더 실행하면, DynamoDB Local은 그 단일 DeleteRequest에 대해 2.0단위를 보고합니다. BatchWriteItem 레퍼런스(2026-07-28 확인)는 존재하지 않는 항목에 대한 삭제가 쓰기 용량 단위 1개를 소비한다고 문서화하고 있고, 같은 로컬 엔진에 대한 단독 delete-item은 실제로 1.0을 보고합니다. 로컬의 용량 수치는 방향만 참고하세요. 어느 쪽이든 살아남는 사실은, 아무것도 찾지 못한 삭제에도 과금된다는 점입니다.

서비스가 곧바로 거절하는 요청이 둘 있으며, stderr에 출력되고 종료 상태는 254입니다:

aws: [ERROR]: An error occurred (ValidationException) when calling the BatchWriteItem operation: Too many items requested for the BatchWriteItem call
aws: [ERROR]: An error occurred (ValidationException) when calling the BatchWriteItem operation: Provided list of item keys contains duplicates

두 번째는 한참 들여다볼 값어치가 있습니다. 이것은 put 두 개가 아니라 같은 키에 대한 PutRequest와 DeleteRequest가 만들어 낸 것입니다. DynamoDB는 한 배치 안에서 한 항목에 가해지는 두 번째 작업을 무엇이든 중복으로 세므로, "옛 행을 지우고 새 행을 쓴다"는 두 항목이 전혀 닮지 않았는데도 하나의 배치로는 실패합니다.

그 값 맵들을 작은따옴표 안에서 조립하는 데 시간이 갑니다. DynamoDB Expression Builder는 타입이 지정된 맵을 만들고 실행 가능한 명령을 복사해 주므로, 실패하더라도 최소한 엉뚱한 역슬래시가 아니라 진짜 실패입니다.

아무것도 이스케이프하지 않고 CSV나 JSON에서 항목을 대량으로 넣거나 지우려면 DynoTable을 다운로드하세요.

참고 자료

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

AWS CLI를 사용한 DynamoDB BatchWriteItem

코드

설명

명령이 출력하는 것, 거부 사례까지

관련 예제

참고 자료