DynamoDB GetItem in Java (AWS SDK v2)

AWS SDK for Java 2.x models an item as a Map<String, AttributeValue> assembled through immutable builders. Two of its conventions differ from most other SDKs: numbers are typed as strings, and response collections are never null.

The request itself needs the full primary key, same as everywhere else.

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.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.model.GetItemRequest;

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

            Map<String, AttributeValue> key = new HashMap<>();
            key.put("Artist", AttributeValue.builder().s("Arturo Sandoval").build());
            key.put("SongTitle", AttributeValue.builder().s("Cubano Chant").build());

            Map<String, String> names = new HashMap<>();
            names.put("#proj0", "Artist");
            names.put("#proj1", "SongTitle");
            names.put("#proj2", "AlbumTitle");
            names.put("#proj3", "Year");

            GetItemRequest request = GetItemRequest.builder()
                    .tableName("Music")
                    .key(key)
                    .projectionExpression("#proj0, #proj1, #proj2, #proj3")
                    .expressionAttributeNames(names)
                    .build();

            Map<String, AttributeValue> item = ddb.getItem(request).item();
            if (item.isEmpty()) {
                System.out.println("Item not found");
            } else {
                System.out.println(item);
            }
        } catch (DynamoDbException e) {
            System.err.println(e.getMessage());
        }
    }
}

Explanation

n() takes a String — AttributeValue.builder().n(1994) does not compile. The Javadoc gives the reason: "Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries." So it is n("1994"), and parsing on the way back out is yours.
item() never returns null — a miss yields an empty map, so isEmpty() is the test. To separate "the service returned nothing" from "the service returned an empty map", call hasItem(); the SDK auto-constructs empty collections and hasItem() is the only thing that sees through that.
The map it hands back is immutable — the Javadoc is explicit that modifying it throws UnsupportedOperationException. Copy into a HashMap first if you plan to edit.
Nothing validates the alias map locally — expressionAttributeNames is a plain Map<String, String>. #proj3 is required here because Year is a reserved word, and an alias you declare but never reference is its own service-side error: "Value provided in ExpressionAttributeNames unused in expressions".
One client for the whole application — AWS states it plainly: "Service clients in the AWS SDK for Java 2.x are thread-safe." The try-with-resources block suits a one-shot main; in a long-running service, build the client at startup and never close it per request.
.consistentRead(true) doubles the read cost and is rejected on a GSI. If AttributeValue maps wear thin, the DynamoDB Enhanced Client (software.amazon.awssdk.enhanced.dynamodb) maps items onto annotated beans over these same low-level calls.

Do it visually

Whether this read bills 0.5 or 1 capacity unit comes down to whether the item fits inside 4 KB. The item size calculator measures a pasted item against that boundary.

DynoTable shows the same items as ordinary rows, and exports the query behind the grid as a Java program built from these builders. Download DynoTable.

DynamoDB GetItem in Go — the same read with AWS SDK for Go v2.
DynamoDB Query in Java — read a whole partition instead of one item.
How DynamoDB partition keys work — why GetItem needs the full key.
DynamoDB ResourceNotFoundException — the usual first error here: wrong table name or region.
"The provided key element does not match the schema" — the key you pass doesn't match the table's key schema.

References

Last verified 2026-07-28 against the official AWS documentation linked above.

DynamoDB GetItem in Java (AWS SDK v2)

Code

Explanation

Do it visually

Related examples

References