Use advanced mapping features - Amazon SDK for Java 2.x
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Use advanced mapping features

Learn about advanced table schema features in the DynamoDB Enhanced Client API.

Understand table schema types

TableSchema is the interface to the mapping functionality of the DynamoDB Enhanced Client API. It can map a data object to and from a map of AttributeValues. A TableSchema object needs to know about the structure of the table it is mapping. This structure information is stored in a TableMetadata object.

The enhanced client API has several implementations of TableSchema, which follow.

Table schema generated from annotated classes

It is a moderately expensive operation to build a TableSchema from annotated classes, so we recommend doing this once, at application startup.


This implementation is built based on attributes and annotations of a bean class. An example of this approach is demonstrated in the Get started section.


If a BeanTableSchema is not behaving as you expect, enable debug logging for


This implementation is built from an immutable data class. This approach is described in the Work with immutable data classes section.

Table schema generated with a builder

The following TableSchemas are built from code by using a builder. This approach is less costly than the approach that uses annotated data classes. The builder approach avoids the use of annotations and doesn't require JavaBean naming standards.


This implementation is built for mutable data classes. The getting started section of this guide demonstrated how to generate a StaticTableSchema using a builder.


Similarly to how you build a StaticTableSchema, you generate an implementation of this type of TableSchema using a builder for use with immutable data classes.

Table schema for data without a fixed schema


Unlike other implementations of TableSchema, you don't define attributes for a DocumentTableSchema instance. Usually, you specify only primary keys and attribute converter providers. An EnhancedDocument instance provides the attributes that you build from individual elements or from a JSON string.