Dynamo Mapper

August 16, 2026 · View on GitHub

GitHub branch status Latest Release GitHub last commit License

A simple mapper for converting to and from DynamoDB AttributeValues and POJOs using Jackson.

Installation

Dynamo Mapper is available from Maven Central.

Gradle

implementation 'com.autonomouslogic.dynamomapper:dynamo-mapper:version'

Maven

<dependency>
    <groupId>com.autonomouslogic.dynamomapper</groupId>
    <artifactId>dynamo-mapper</artifactId>
    <version>version</version>
</dependency>

Dynamo Mapper functions as a wrapper around the existing AWS DynamoDB v2 SDK. First, you need to construct a DynamoDB client object and a Jackson ObjectMapper, and then pass those to the Dynamo Mapper builder. If you do not provide a DynamoDB client or Jackson ObjectMapper, defaults will be used.

var dynamoMapper = DynamoMapper.builder()
    .client(DynamoDbClient.create())
    .objectMapper(new ObjectMapper())
    .tableNameDecorator(decorator) // optional
    .build();

Or, for the asynchronous API:

var asyncDynamoMapper = DynamoAsyncMapper.builder()
    .client(DynamoDbAsyncClient.create())
    .objectMapper(new ObjectMapper())
	.tableNameDecorator(decorator) // optional
    .build();

Defining schemas

Dynamo Mapper relies on Jackson for its serialization. Generally, anything that works in Jackson will work in Dynamo Mapper. Only a few extra annotations are required.

@DynamoTableName("table-name")
public class ModelObject {
	@JsonProperty
	@DynamoPrimaryKey
	private String primaryKey;
	
	@JsonProperty
	private String otherValue;
	
	/* etc. */
}

Getting items

Using the synchronous API:

var item = dynamoMapper.getItemFromPrimaryKey("key-value", ModelObject.class).item();

Using the asynchronous API:

dynamoMapper.getItemFromPrimaryKey("key-value", ModelObject.class).thenAccept(response -> {
	var item = response.item();
});

Putting items

Using the synchronous API:

var item = new ModelObject().setPrimaryKey("key-value");
var response = dynamoMapper.putItemFromKeyObject(item);

Using the asynchronous API:

var item = new ModelObject().setPrimaryKey("key-value");
dynamoMapper.putItemFromKeyObject(item).thenAccept(response -> {
	// etc.
});

Best practices

Jackson will include all null values, to prevent this taking up space in DynamoDB, use @JsonInclude(JsonInclude.Include.NON_NULL)
To properly serialize BigDecimals, use objectMapper.enable(JsonGenerator.Feature.WRITE_BIGDECIMAL_AS_PLAIN)
To encode java.time objects properly, use jackson-datatype-jsr310

Number precision limits

DynamoDB stores numbers with a maximum of 38 significant digits of precision and an exponent range of 10^-130 to 10¹²⁵. This means arbitrarily large BigInteger and BigDecimal values cannot be stored. See the AWS documentation: API reference - AttributeValue

Jackson version

Jackson 3 continues to use the Jackson 2 variant of jackson-annotations, so while this mapper uses Jackson 3, most existing use of Jackson 2 should be backwards-compatible.

Jackson Release 3.0

Comparison with DynamoDBMapper and DynamoDB Enhanced

The DynamoDBMapper in the v1 AWS SDK and the DynamoDB Enhanced Client in the v2 AWS SDK both provide similar mapping functionality.

This idea for this library was originally created to provide the same mapping as the v1 mapper, but for the v2 SDK, before the enhanced client was released. The v2 SDK now provides this mapping functionality officially, but has a few short-comings. For instance, the annotations must be added to methods and not properties. This makes Lombok models useless. Jackson is a widely used and mature library. with advanced features that will never, and shouldn't, be implemented in the enhanced client.

There are some cons to doing it this way. For instance, it's not possible to have a different schema in the DynamoDB and JSON versions of an object.