AWS CLI로 하는 DynamoDB PutItem

aws dynamodb put-item은 항목 전체를 쓰고 같은 기본 키를 가진 기존 항목을 대체합니다(항목 기반 작업에서 update-item과 어떻게 다른지 다룹니다). CLI가 문제에 보태는 것은 셸입니다. --item은 DynamoDB JSON을 따옴표로 묶인 인자 하나로 받고, 모든 속성 값에는 타입이 붙습니다.

코드

aws dynamodb put-item \
  --table-name 'Music' \
  --item '{"Artist":{"S":"Arturo Sandoval"},"SongTitle":{"S":"Cubano Chant"},"AlbumTitle":{"S":"Danzon"},"Year":{"N":"1994"},"Awards":{"N":"0"}}' \
  --condition-expression 'attribute_not_exists(#cond0) AND attribute_not_exists(#cond1)' \
  --expression-attribute-names '{"#cond0":"Artist","#cond1":"SongTitle"}'

성공하면 명령은 아무것도 출력하지 않고 0으로 종료합니다. 항목이 이미 존재하면 조건이 실패합니다:

An error occurred (ConditionalCheckFailedException) when calling the PutItem operation:
The conditional request failed

설명

침묵과 종료 코드 0이 유일한 성공 신호입니다. put-item은 --return-values를 요청하지 않는 한 JSON을 출력하지 않으므로, 확인을 위해 stdout을 grep하는 스크립트는 영원히 걸리지 않습니다. $?를 확인하세요. 위 명령을 aws-cli/2.36.9에서 두 번 실행하면 이렇게 나옵니다:

first run:   (no output)                exit 0
second run:  aws: [ERROR]: An error occurred (ConditionalCheckFailedException) when calling the PutItem operation: The conditional request failed
             exit 254

254는 "CLI가 고장 났다"가 아니라 "서비스가 거절했다"입니다. AWS CLI는 자체 문법·설정 문제에 252/253을, 그 밖의 모든 것에 255를 예약해 두었으므로 ConditionalCheckFailedException도, ValidationException도, 스로틀링도 모두 같은 254에 떨어집니다. 스크립트가 예상된 조건 실패와 진짜 장애를 구분해야 한다면 종료 코드가 아니라 오류 이름을 파싱하세요. 또한 2.36.9는 메시지 앞에 aws: [ERROR]: 를 붙이는데 예전 빌드는 그러지 않았습니다. ^An error occurred에 고정된 정규식은 CLI를 올리고 나면 조용히 매칭을 멈춥니다.

실패한 조건부 쓰기도 비용을 물립니다. 조건은 서비스가 항목을 찾아낸 뒤에 평가하며, AWS는 "if the expression evaluates to false, DynamoDB still consumes write capacity units from the table"라고 명시합니다(2026-07-28 확인). 생성 전용 put을 감싼 재시도 루프는 시도마다 청구됩니다. 규모 감각을 위해 덧붙이면, 약 15 KB 항목의 성공한 put에 --return-consumed-capacity TOTAL을 붙였더니 "CapacityUnits": 15가 보고되었습니다. 쓰기는 읽기가 쓰는 4 KB가 아니라 1 KB 단위로 올림합니다.

--return-values-on-condition-check-failure는 동작하지만 CLI가 답을 감춥니다. 이것은 두 번째 읽기 없이 어떤 항목이 쓰기를 막았는지 알려 주는 플래그입니다. 붙이면 2.36.9는 이렇게 출력합니다:

aws: [ERROR]: An error occurred (ConditionalCheckFailedException) when calling the PutItem operation: The conditional request failed

Additional error details:
Item: <complex value>
Use "--cli-error-format json" or another error format to see the full details.

항목은 내내 응답 안에 들어 있습니다. 기본 오류 포매터가 그것을 렌더링하기를 거부할 뿐입니다. --cli-error-format json을 붙이면 얻을 수 있습니다. (--return-values ALL_OLD는 조건이 없는 사촌으로 성공했을 때만 발동합니다. ReturnValues에서 다섯 가지 옵션을 다룹니다.)

따옴표 처리가 나머지 절반의 일입니다. --item 인자는 따옴표로 감싼 숫자({"N": "1994"}이지 결코 1994가 아닙니다)를 담은 JSON을 담은 셸 토큰 하나입니다. 아포스트로피가 들어간 것이나 수백 바이트를 넘는 항목은 --item file://song.json이 더 편합니다. --cli-input-json file://request.json은 한 걸음 더 나아가 조건 표현식을 포함한 요청 전체를 받으며, 리뷰에서 diff를 볼 수 있는 형태이기도 합니다.

별칭은 선택적인 장식이 아닙니다. #cond0/#cond1은 --expression-attribute-names를 통해 Artist/SongTitle로 풀립니다. 이름을 인라인으로 쓰는 것은 그중 하나가 예약어와 충돌하기 전까지만 통하며, 그 순간 명령은 여러분이 건드리지도 않은 이름 때문에 실패합니다.

시각적으로 해보기

--item에 넣을 타입 붙은 JSON을 손으로 치는 지점에서 이 명령들 대부분이 죽습니다. 무료 DynamoDB JSON 변환기는 평범한 JSON을 받아 플래그가 원하는 {"S": …} / {"N": …} 형태로 돌려주며, 그대로 file:// 페이로드로 저장할 수 있습니다.

여러분의 테이블에 항목을 추가하고 편집하려면 — 속성마다 하나의 폼, 타입 선택기, 결과를 다시 CLI 명령으로 복사 — DynoTable을 다운로드하세요.

참고 자료

2026-07-28에 aws-cli/2.36.9로 포트 9000의 DynamoDB Local(amazon/dynamodb-local)을 상대로 재현했습니다. 종료 코드, 오류 텍스트, 용량 수치는 그대로 옮긴 출력입니다. 실패한 쓰기의 용량 소비는 측정이 아니라 AWS 문서에서 인용했습니다. DynamoDB Local은 조건 실패 경로에서 ConsumedCapacity를 반환하지 않기 때문입니다.

AWS CLI로 하는 DynamoDB PutItem

코드

설명

시각적으로 해보기

관련 가이드

참고 자료