DynamoDB PutItem in Go (AWS SDK v2)

PutItem schreibt ein ganzes Item und erstellt es oder ersetzt jedes bestehende Item mit demselben Primärschlüssel. Im AWS SDK for Go v2 rufst du client.PutItem mit einem dynamodb.PutItemInput auf, dessen Item-Map jedes Attribut als typisierten Wert aus dem types-Paket hält.

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")
}

Um die Item-Map stattdessen aus einem schlichten Go-Struct zu bauen, nutze attributevalue.MarshalMap aus github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue.

Erklärung

• Item — muss den vollständigen Primärschlüssel der Tabelle enthalten, plus alle weiteren Attribute. Zahlen sind Strings innerhalb von AttributeValueMemberN ({Value: "1994"}).
• Put ersetzt — ohne Bedingung überschreibt PutItem stillschweigend ein bestehendes Item mit demselben Schlüssel. Nutze UpdateItem, um einige Attribute zu ändern, ohne den Rest zu überschreiben.
• ConditionExpression — attribute_not_exists(...) auf den Schlüsselattributen macht den Write zu einem nur-erstellenden Insert; der Write schlägt mit ConditionalCheckFailedException fehl, wenn das Item bereits existiert. Das ist DynamoDBs Primitiv für optimistisches Locking. Die Aliase #cond0/#cond1 lösen per ExpressionAttributeNames zu Artist/SongTitle auf (reservierte-Wort-sicher).
• errors.As — das Go-SDK umschließt Service-Fehler, also matche den typisierten *types.ConditionalCheckFailedException mit errors.As, niemals per String-Vergleich.
• Um das überschriebene Item zurückzubekommen, setze ReturnValues: types.ReturnValueAllOld.

Visuell erledigen

Einen bedingten Put von Hand schreiben? Der DynamoDB Expression Builder stellt die ConditionExpression zusammen und kopiert den Code.

Um Items in einer GUI hinzuzufügen und zu bearbeiten — ein Formular pro Attribut, Typ-Auswahl und Copy-as-Code — lade DynoTable herunter.

Verwandte Beispiele

• DynamoDB PutItem in Java — derselbe bedingte Write mit AWS SDK for Java 2.x.
• DynamoDB UpdateItem in Go — bestimmte Attribute ändern, statt das Item zu ersetzen.
• DynamoDB-Bedingungsausdrücke — attribute_not_exists, optimistisches Locking und mehr.
• DynamoDB ConditionalCheckFailedException — was die nur-erstellende Bedingung wirft, wenn das Item bereits existiert.
• DynamoDB ValidationException — der Sammelfehler für ein fehlerhaftes Item oder eine fehlerhafte Expression.

References

• PutItem — Amazon DynamoDB API Reference
• Use PutItem with an AWS SDK or CLI — Amazon DynamoDB Developer Guide
• dynamodb package — AWS SDK for Go v2 (pkg.go.dev)
• dynamodb/types package — AWS SDK for Go v2 (pkg.go.dev)
• Handling errors — AWS SDK for Go v2 Developer Guide
• Condition expressions — Amazon DynamoDB Developer Guide

Zuletzt verifiziert am 2026-07-13 gegen die oben verlinkte offizielle AWS-Dokumentation.