Using the Object Persistence Model with Amazon DynamoDB

Identifies the target table in Amazon DynamoDB. For example, the following Java code snippet defines a class Developer and maps it to the People table in Amazon DynamoDB.

@DynamoDBTable(tableName="People") 
public class Developer { ...}

This annotation can be inherited or overridden.

Indicates to the DynamoDBMapper instance that the associated property should be ignored. When saving data to the table, the DynamoDBMapper does not save this property to the table.

Maps a property to a table attribute. By default, each class property maps to an item attribute with the same name. However, if the names are not the same, using this tag you can map a property to the attribute. In the following Java snippet, the DynamoDBAttribute maps the BookAuthors property to the Authors attribute name in the table.

@DynamoDBAttribute(attributeName = "Authors")
public List<String> getBookAuthors() { return BookAuthors; }
public void setBookAuthors(List<String> BookAuthors) { this.BookAuthors = BookAuthors; }

The DynamoDBMapper uses Authors as the attribute name when saving the object to the table.

Maps a class property to the hash attribute of the table. The property must be one of the supported String or Numeric type and cannot be a collection type.

Assume that you have a table, ProductCatalog, that has Id as the primary key. The following Java code snippet defines a CatalogItem class and maps its Id property to the primary key of the ProductCatalog table using the @DynamoDBHashKey tag.

@DynamoDBTable(tableName="ProductCatalog") 
public class CatalogItem { 
    private String Id;   
   @DynamoDBHashKey(attributeName="Id")
   public String getId() {
        return Id;
   }
   public void setId(String Id) {
        this.Id = Id;
   }
   // Additional properties go here. 
}

Maps a class property to the range key attribute of the table. If the primary key is made of both the hash and range key attributes, you can use this tag to map your class field to the range attribute. For example, assume that you have a Reply table that stores replies for forum threads. Each thread can have many replies. So the primary key of this table is both the ThreadId and ReplyDateTime. The ThreadId is the hash attribute and ReplyDateTime is the range attribute. The following Java code snippet defines a Reply class and maps it to the Reply table. It uses both the @DynamoDBHashKey and @DynamoDBRangeKey tags to identify class properties that map to the primary key.

@DynamoDBTable(tableName="Reply")
public class Reply { 
    private String id;
    private String replyDateTime;

    @DynamoDBHashKey(attributeName="Id")
    public String getId() { return id; }
    public void setId(String id) { this.id = id; } 

    @DynamoDBRangeKey(attributeName="ReplyDateTime")
    public String getReplyDateTime() { return replyDateTime; }
    public void setReplyDateTime(String replyDateTime) { this.replyDateTime = replyDateTime; } 

   // Additional properties go here. 
}

Marks a hash key or range key property as being auto-generated. The Object Persistence Model will generate a random UUID when saving these attributes. Only String properties can be marked as auto-generated keys.

The following snippet demonstrates using auto-generated keys.

@DynamoDBTable(tableName="AutoGeneratedKeysExample")
public class AutoGeneratedKeys { 
    private String id;
    private String payload;
    
    @DynamoDBHashKey(attributeName = "Id")
    @DynamoDBAutoGeneratedKey
    public String getId() { return id; }
    public void setId(String id) { this.id = id; } 

    @DynamoDBAttribute(attributeName="payload")
    public String getPayload() { return this.payload };
    public String setPayload(String payload) { this.payload = payload };	
   
    public static void saveItem() {
        AutoGeneratedKeys obj = new AutoGeneratedKeys();
        obj.setPayload("abc123");
		
        // id field is null at this point		
        DynamoDBMapper mapper = new DynamoDBMapper(dynamoDBClient);
        mapper.save(obj);
        
        System.out.println("Object was saved with id " + obj.getId());
    }
}                         

Saves the specified object to the table. The object that you wish to save is the only required parameter for this method. You can provide optional configuration parameters using the DynamoDBMapperConfig object.

If an item that has the same primary key does not exist, this method creates a new item in the table. If an item that has the same primary key exists, it updates the existing item. String hash and range keys annotated with @DynamoDBAutoGeneratedKey are given a random universally unique identifier (UUID) if left uninitialized. Version fields annotated with @DynamoDBVersionAttribute will be incremented by one. Additionally, if a version field is updated or a key generated, the object passed in is updated as a result of the operation.

By default, only attributes corresponding to mapped class properties are updated; any additional existing attributes on an item are unaffected. However, if you specify SaveBehavior.CLOBBER, you can force the item to be completely overwritten.

mapper.save(obj, new DynamoDBMapperConfig(DynamoDBMapperConfig.SaveBehavior.CLOBBER));

If you have versioning enabled, then the client-side and server-side item versions must match. However, the version does not need to match if the SaveBehavior.CLOBBER option is used. For more information about versioning, see Optimistic Locking With Version Number Using the AWS SDK for Java Object Persistence Model.

Retrieves an item from a table. You must provide the primary key of the item that you wish to retrieve. You can provide optional configuration parameters using the DynamoDBMapperConfig object. For example, you can optionally request strongly consistent reads to ensure that this method retrieves only the latest item values as shown in the following Java statement.

CatalogItem item = mapper.load(CatalogItem.class, item.getId(), 
                new DynamoDBMapperConfig(DynamoDBMapperConfig.ConsistentReads.CONSISTENT)); 

By default, Amazon DynamoDB returns the item that has values that are eventually consistent. For information about the eventual consistency model of Amazon DynamoDB, see Data Read and Consistency Considerations.

Deletes an item from the table. You must pass in an object instance of the mapped class.

If you have versioning enabled, then the client-side and server-side item versions must match. However, the version does not need to match if the SaveBehavior.CLOBBER option is used. For more information about versioning, see Optimistic Locking With Version Number Using the AWS SDK for Java Object Persistence Model.

Enables the querying of a table. You can query a table only if its primary key is made of both a hash and a range attribute. This method requires you to provide a hash attribute value and a query filter that is applied on the range attribute. A filter expression includes a condition and a value.

Assume that you have a table, Reply, that stores forum thread replies. Each thread subject can have 0 or more replies. The primary key of the Reply table consists of the Id and ReplyDateTime fields, where Id is the hash attribute and ReplyDateTime is the range attribute of the primary key.

Reply ( Id, ReplyDateTime, ... )

Now, assume that you created an Object Persistence model that includes a Reply class that maps to the table.

The following Java code snippet uses the DynamoDBMapper instance to query the table to find all replies in the past two weeks for a specific thread subject.

String forumName = "Amazon DynamoDB";
String forumSubject = "DynamoDB Thread 1";
String hashKey = forumName + "#" + forumSubject;

long twoWeeksAgoMilli = (new Date()).getTime() - (14L*24L*60L*60L*1000L);
Date twoWeeksAgo = new Date();
twoWeeksAgo.setTime(twoWeeksAgoMilli);
SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'");
String twoWeeksAgoStr = df.format(twoWeeksAgo);


Condition rangeKeyCondition = new Condition()
    .withComparisonOperator(ComparisonOperator.GT.toString())
    .withAttributeValueList(new AttributeValue().withS(twoWeeksAgoStr.toString()));

Reply replyKey = new Reply();
replyKey.setId(hashKey);

DynamoDBQueryExpression<Reply> queryExpression = new DynamoDBQueryExpression<Reply>()
    .withHashKeyValues(replyKey)
    .withRangeKeyCondition("ReplyDateTime", rangeKeyCondition);

List<Reply> latestReplies = mapper.query(Reply.class, queryExpression);

The query returns a collection of Reply objects.

The query method returns a "lazy-loaded" collection. It initially returns only one page of results, and then makes a service call for the next page if needed. To obtain all the matching items, you only need to iterate over the latestReplies collection.

Scans an entire table. You can specify optional condition filters items based on one or more Condition instances, and you can specify a filter expression for any item attributes.

Assume that you have a table, Thread, that stores forum thread information including Subject (part of the composite primary key) and if the thread is answered.

Thread ( ForumName, Subject, ..., Answered )

If you have an Object Persistence model for this table, then you can use the DynamoDBContext to scan the table. For example, the following Java code snippet filters the Thread table to retrieve all the unanswered threads. The scan condition identifies the attribute and a condition.

DynamoDBScanExpression scanExpression = new DynamoDBScanExpression();
        
Map<String, Condition> scanFilter = new HashMap<String, Condition>();
Condition scanCondition = new Condition()
    .withComparisonOperator(ComparisonOperator.EQ.toString())
    .withAttributeValueList(new AttributeValue().withN("0"));

scanFilter.put("Answered", scanCondition);
        
scanExpression.setScanFilter(scanFilter);

List<Thread> unansweredThreads = mapper.scan(Thread.class, scanExpression);

The scan method returns a "lazy-loaded" collection. It initially returns only one page of results, and then makes a service call for the next page if needed. To obtain all the matching items, you only need to iterate over the unansweredThreads collection.

Deletes objects from one or more tables using one or more calls to the AmazonDynamoDB.batchWriteItem method. This method does not provide transaction guarantees.

The following Java code snippet deletes two items (books) from the ProductCatalog table.

Book book1 = mapper.load(Book.class, 901);
Book book2 = mapper.load(Book.class, 902);
mapper.batchDelete(Arrays.asList(book1, book2));

Saves objects to one or more tables using one or more calls to the AmazonDynamoDB.batchWriteItem method. This method does not provide transaction guarantees.

The following Java code snippet saves two items (books) to the ProductCatalog table.

Book book1 = new Book();
book1.id = 901;
book1.productCategory = "Book";
book1.title = "Book 901 Title";

Book book2 = new Book();
book2.id = 902;
book2.productCategory = "Book";
book2.title = "Book 902 Title";

mapper.batchSave(Arrays.asList(book1, book2));

Saves objects to and deletes objects from one or more tables using one or more calls to the AmazonDynamoDB.batchWriteItem method. This method does not provide transaction guarantees or support versioning (conditional puts or deletes).

The following Java code snippet writes a new item to the Forum table, writes a new item to the Thread table, and deletes an item from the ProductCatalog table.

// Create a Forum item to save
Forum forumItem = new Forum();
forumItem.name = "Test BatchWrite Forum";
        
// Create a Thread item to save
Thread threadItem = new Thread();
threadItem.forumName = "AmazonDynamoDB";
threadItem.subject = "My sample question";
        
// Load a ProductCatalog item to delete
Book book3 = mapper.load(Book.class, 903);
        
List<Object> objectsToWrite = Arrays.asList(forumItem, threadItem);
List<Book> objectsToDelete = Arrays.asList(book3); 
       
mapper.batchWrite(objectsToWrite, objectsToDelete);

Evaluates the specified scan expression and returns the count of matching items. No item data is returned.

Utility method to transform a result from the low-level API into a domain object.

All number types

N (number type)

Strings

S (string type)