DynamoDB PutItem en Go (AWS SDK v2)

PutItem escribe un item completo, creándolo o reemplazando cualquier item existente con la misma clave primaria. En AWS SDK para Go v2 llamas a client.PutItem con un dynamodb.PutItemInput cuyo mapa Item contiene cada atributo como un valor tipado del paquete types.

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

Para construir el mapa Item a partir de una struct de Go plana en su lugar, usa attributevalue.MarshalMap de github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue.

Explicación

Item — debe contener la clave primaria completa de la tabla, más cualquier otro atributo. Los números son strings dentro de AttributeValueMemberN ({Value: "1994"}).
Put reemplaza — sin condición, PutItem sobrescribe silenciosamente un item existente con la misma clave. Usa UpdateItem para cambiar unos pocos atributos sin arrasar el resto.
ConditionExpression — attribute_not_exists(...) sobre los atributos de clave convierte la escritura en una inserción solo de creación; la escritura falla con ConditionalCheckFailedException si el item ya existe. Este es el primitivo de bloqueo optimista de DynamoDB. Los alias #cond0/#cond1 se resuelven a Artist/SongTitle mediante ExpressionAttributeNames (a salvo de palabras reservadas).
errors.As — el SDK de Go envuelve los errores de servicio, así que empareja el tipado *types.ConditionalCheckFailedException con errors.As, nunca por comparación de strings.
Para recuperar el item sobrescrito, pon ReturnValues: types.ReturnValueAllOld.

Hazlo visualmente

¿Escribiendo un put condicional a mano? El DynamoDB Expression Builder monta el ConditionExpression y copia el código.

Para añadir y editar items en una interfaz gráfica — un formulario por atributo, selectores de tipo, y copiar como código — descarga DynoTable.

Ejemplos relacionados

DynamoDB PutItem en Java — la misma escritura condicional con AWS SDK para Java 2.x.
DynamoDB UpdateItem en Go — cambia atributos concretos en lugar de reemplazar el item.
Expresiones de condición de DynamoDB — attribute_not_exists, bloqueo optimista y más.
DynamoDB ConditionalCheckFailedException — lo que lanza la condición solo-de-creación cuando el item ya existe.
DynamoDB ValidationException — el error genérico para un item o expresión mal formados.

References

Verificado por última vez el 2026-07-13 contra la documentación oficial de AWS enlazada arriba.