Go(AWS SDK v2)에서의 DynamoDB PutItem

PutItem은 항목 전체를 쓰며, 항목을 생성하거나 동일한 기본 키를 가진 기존 항목을 교체합니다. AWS SDK for Go v2에서는 Item 맵이 모든 속성을 types 패키지의 타입 지정 값으로 담는 dynamodb.PutItemInput과 함께 client.PutItem을 호출합니다.

Code

package main

import (
	"context"
	"errors"
	"fmt"
	"log"

	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/config"
	"github.com/aws/aws-sdk-go-v2/service/dynamodb"
	"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
)

func main() {
	ctx := context.TODO()
	cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion("us-east-1"))
	if err != nil {
		log.Fatalf("load config: %v", err)
	}
	client := dynamodb.NewFromConfig(cfg)

	_, err = client.PutItem(ctx, &dynamodb.PutItemInput{
		TableName: aws.String("Music"),
		Item: map[string]types.AttributeValue{
			"Artist":     &types.AttributeValueMemberS{Value: "Arturo Sandoval"},
			"SongTitle":  &types.AttributeValueMemberS{Value: "Cubano Chant"},
			"AlbumTitle": &types.AttributeValueMemberS{Value: "Danzon"},
			"Year":       &types.AttributeValueMemberN{Value: "1994"},
			"Awards":     &types.AttributeValueMemberN{Value: "0"},
		},
		ConditionExpression: aws.String("attribute_not_exists(#cond0) AND attribute_not_exists(#cond1)"),
		ExpressionAttributeNames: map[string]string{
			"#cond0": "Artist",
			"#cond1": "SongTitle",
		},
	})
	if err != nil {
		var ccf *types.ConditionalCheckFailedException
		if errors.As(err, &ccf) {
			fmt.Println("A song with that key already exists — not overwritten")
			return
		}
		log.Fatalf("put item: %v", err)
	}
	fmt.Println("Song written")
}

대신 평범한 Go 구조체에서 Item 맵을 만들려면 github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue의 attributevalue.MarshalMap을 사용하세요.

Explanation

Item — 테이블의 전체 기본 키와 그 밖의 속성을 포함해야 합니다. 숫자는 AttributeValueMemberN 안에서 문자열입니다({Value: "1994"}).
Put은 교체함 — 조건이 없으면 PutItem은 동일한 키를 가진 기존 항목을 조용히 덮어씁니다. 나머지를 건드리지 않고 일부 속성만 변경하려면 UpdateItem을 사용하세요.
ConditionExpression — 키 속성에 대한 attribute_not_exists(...)는 쓰기를 생성 전용 삽입으로 만듭니다. 항목이 이미 존재하면 쓰기는 ConditionalCheckFailedException으로 실패합니다. 이것이 DynamoDB의 낙관적 잠금 프리미티브입니다. #cond0/#cond1 별칭은 ExpressionAttributeNames를 통해 Artist/SongTitle로 해석됩니다(예약어 안전).
errors.As — Go SDK는 서비스 오류를 래핑하므로, 문자열 비교가 아니라 errors.As로 타입 지정 *types.ConditionalCheckFailedException을 매칭하세요.
덮어쓴 항목을 되돌려 받으려면 ReturnValues: types.ReturnValueAllOld를 설정하세요.

Do it visually

조건부 put을 손으로 작성하고 계신가요? DynamoDB Expression Builder는 ConditionExpression을 조립하고 코드를 복사해 줍니다.

GUI에서 항목을 추가하고 편집하려면 — 속성별 폼, 타입 선택기, 코드로 복사 — DynoTable을 다운로드하세요.

DynamoDB PutItem in Java — AWS SDK for Java 2.x를 사용한 동일한 조건부 쓰기.
DynamoDB UpdateItem in Go — 항목을 교체하는 대신 특정 속성을 변경하기.
DynamoDB condition expressions — attribute_not_exists, 낙관적 잠금 등.
DynamoDB ConditionalCheckFailedException — 항목이 이미 존재할 때 생성 전용 조건이 발생시키는 것.
DynamoDB ValidationException — 잘못된 형식의 항목이나 표현식을 위한 포괄 오류.

References

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

Go(AWS SDK v2)에서의 DynamoDB PutItem

Code

Explanation

Do it visually

Related examples

References