DynamoDB PutItem em Java (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 Java 2.x você constrói um PutItemRequest cujo mapa item contém cada atributo como um AttributeValue tipado (.s(...) para strings, .n(...) para números).

Code

import java.util.HashMap;
import java.util.Map;

import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.ConditionalCheckFailedException;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.model.PutItemRequest;

public class PutItemExample {
    public static void main(String[] args) {
        try (DynamoDbClient ddb = DynamoDbClient.builder()
                .region(Region.US_EAST_1)
                .build()) {

            Map<String, AttributeValue> item = new HashMap<>();
            item.put("Artist", AttributeValue.builder().s("Arturo Sandoval").build());
            item.put("SongTitle", AttributeValue.builder().s("Cubano Chant").build());
            item.put("AlbumTitle", AttributeValue.builder().s("Danzon").build());
            item.put("Year", AttributeValue.builder().n("1994").build());
            item.put("Awards", AttributeValue.builder().n("0").build());

            Map<String, String> names = new HashMap<>();
            names.put("#cond0", "Artist");
            names.put("#cond1", "SongTitle");

            PutItemRequest request = PutItemRequest.builder()
                    .tableName("Music")
                    .item(item)
                    .conditionExpression("attribute_not_exists(#cond0) AND attribute_not_exists(#cond1)")
                    .expressionAttributeNames(names)
                    .build();

            try {
                ddb.putItem(request);
                System.out.println("Song written");
            } catch (ConditionalCheckFailedException e) {
                System.out.println("A song with that key already exists — not overwritten");
            }
        } catch (DynamoDbException e) {
            System.err.println(e.getMessage());
        }
    }
}

Explicação

item — deve conter a chave primária completa da tabela, mais quaisquer outros atributos. Números são strings sob o tipo N (AttributeValue.builder().n("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).
ConditionalCheckFailedException estende DynamoDbException — capture-o primeiro (o try interno acima) para que a condição falha seja tratada separadamente de outros erros de serviço.
Para obter de volta o item sobrescrito, adicione .returnValues(ReturnValue.ALL_OLD).
Prefere objetos Java simples? O DynamoDB Enhanced Client (software.amazon.awssdk.enhanced.dynamodb) grava classes bean anotadas em vez de mapas de AttributeValue.

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 Go — a mesma gravação condicional com o AWS SDK for Go v2.
DynamoDB UpdateItem em Java — 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.