DynamoDB PutItem en Java (AWS SDK v2)

PutItem escribe un item completo, creándolo o reemplazando cualquier item existente con la misma clave primaria. En AWS SDK para Java 2.x construyes un PutItemRequest cuyo mapa item contiene cada atributo como un 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());
        }
    }
}

Explicación

item — debe contener la clave primaria completa de la tabla, más cualquier otro atributo. Los números son strings bajo el tipo N (AttributeValue.builder().n("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).
ConditionalCheckFailedException extiende DynamoDbException — captúrala primero (el try interno de arriba) para que la condición fallida se gestione por separado de otros errores de servicio.
Para recuperar el item sobrescrito, añade .returnValues(ReturnValue.ALL_OLD).
¿Prefieres objetos Java simples? El DynamoDB Enhanced Client (software.amazon.awssdk.enhanced.dynamodb) escribe clases de bean anotadas en lugar de mapas de AttributeValue.

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 Go — la misma escritura condicional con AWS SDK para Go v2.
DynamoDB UpdateItem en Java — 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.