DynamoDB PutItem em Go (AWS SDK v2)

PutItem grava um item inteiro, criando-o ou substituindo qualquer item existente com a mesma chave primária. No AWS SDK for Go v2 você chama client.PutItem com um dynamodb.PutItemInput cujo mapa Item contém cada atributo como um valor tipado do pacote 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 o mapa Item a partir de uma struct Go simples, use attributevalue.MarshalMap de github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue.

Explicação

Item — deve conter a chave primária completa da tabela, mais quaisquer outros atributos. Números são strings dentro de AttributeValueMemberN ({Value: "1994"}).
Put substitui — sem uma condição, PutItem sobrescreve silenciosamente um item existente com a mesma chave. Use UpdateItem para alterar alguns atributos sem apagar o resto.
ConditionExpression — attribute_not_exists(...) nos atributos da chave torna a gravação uma inserção somente-criação; a gravação falha com ConditionalCheckFailedException se o item já existir. Este é o primitivo de optimistic locking do DynamoDB. Os aliases #cond0/#cond1 resolvem para Artist/SongTitle via ExpressionAttributeNames (seguro contra palavras reservadas).
errors.As — o SDK Go envolve os erros de serviço, então corresponda o tipado *types.ConditionalCheckFailedException com errors.As, nunca por comparação de string.
Para obter de volta o item sobrescrito, defina ReturnValues: types.ReturnValueAllOld.

Faça visualmente

Escrevendo um put condicional na mão? O DynamoDB Expression Builder monta a ConditionExpression e copia o código.

Para adicionar e editar itens numa GUI — um formulário por atributo, seletores de tipo e copiar como código — baixe o DynoTable.

Exemplos relacionados

DynamoDB PutItem em Java — a mesma gravação condicional com o AWS SDK for Java 2.x.
DynamoDB UpdateItem em Go — altere atributos específicos em vez de substituir o item.
Condition expressions do DynamoDB — attribute_not_exists, optimistic locking e mais.
DynamoDB ConditionalCheckFailedException — o que a condição somente-criação lança quando o item já existe.
DynamoDB ValidationException — o erro guarda-chuva para um item ou expressão malformados.

References

Última verificação em 2026-07-13 contra a documentação oficial da AWS vinculada acima.