DynamoDBMapper Query Examples (DynamoDB Java Cheat Sheet)

What is DynamoDBMapper?

DynamoDBMapper is a Java class for Amazon Web Services(AWS). This is the Java DynamoDB NoSQL Database SDK. With DynamoDBMapper, you can set up the relationship between elements in a DynamoDB database table and their related object instances using a domain class.

This cheat sheet is to guide you to set up your Java application, perform create, read, update, and delete (CRUD) operations and run queries using DynamoDBMapper Java class.

If you're looking for similar guide but for Node.js, you can find it here, for Rust, for Python and for Golang / Go here.

Table of Contents

• Setup
• Create Table
• Connection
• Creating a model class
• Put Item
• Get Item
• Update Item
• Batch Put Item
• Batch Put Item & Delete
• Batch Get Items
• Scan with Filter
• Scan Parallel
• Query
• Delete an Item
• Batch Delete Items
• Delete Table
• Run DynamoDB Local

Setup

Prerequisites

• Create a group/user and give AmazonDynamoDBFullAccess policy in IAM.
• Get the Access and Secret Key to configure the Java application.
• Create a Spring Boot Java application.

Note: make sure to install aws-java-SDK-dynamodb dependencies in your pom.xml file in the Java application.

Create a DynamoDB Table

To correctly persist the data, you need to create a table in DynamoDB.You can use AWS Console, Dynobase, AWS CLI, or use AWS-SDK for Java to create a table with a partition key (primary key).

Create a table named Product with ProductID as the partition key.

Note: You can create a table with a sort key (range key) which will be useful for Query. This allows you to retrieve a group of entries within a partition (having the same partition key).

Connection

• Add the Access, Secret Key, and region to store the DynamoDB table.

package com.dynamoDbDemo.config;
import com.amazonaws.auth.AWSStaticCredentialsProvider;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBMapper;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class DynamoDbConfiguration {
    @Bean
    public DynamoDBMapper dynamoDBMapper() {
        return new DynamoDBMapper(buildAmazonDynamoDB());
    }

    private AmazonDynamoDB buildAmazonDynamoDB() {
        return AmazonDynamoDBClientBuilder
                .standard()
                .withRegion("YOUR-REGION")
                .withCredentials(
                        new AWSStaticCredentialsProvider(
                                new BasicAWSCredentials(
                                        "YOUR-ACCESS-KEY",
                                        "YOUR-SECRET-KEY"
                                )
                        )
                )
                .build();
    }
}
package com.dynamoDbDemo.config;
import com.amazonaws.auth.AWSStaticCredentialsProvider;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBMapper;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class DynamoDbConfiguration {
    @Bean
    public DynamoDBMapper dynamoDBMapper() {
        return new DynamoDBMapper(buildAmazonDynamoDB());
    }

    private AmazonDynamoDB buildAmazonDynamoDB() {
        return AmazonDynamoDBClientBuilder
                .standard()
                .withRegion("YOUR-REGION")
                .withCredentials(
                        new AWSStaticCredentialsProvider(
                                new BasicAWSCredentials(
                                        "YOUR-ACCESS-KEY",
                                        "YOUR-SECRET-KEY"
                                )
                        )
                )
                .build();
    }
}

Create a Model Class

Let's create an object called Product which represents an item in a DynamoDB table. The Employee class is accessible via getter and setter methods to correctly persist the data using DynamoDBMapper.

• DynamoDBHashKey : is the Java annotation to map a property to a table attribute.
• DynamoDBHashKey: is the Java annotation for the hash key(partition key) which is the primary key.
• DynamoDBRangeKey: is the Java annotation for the range key(sort key)

@DynamoDBTable(tableName = "Product") //make sure to give the same table name which you provide in AWS Console
public class Product {

  private int productId;
  private String productName;
  private double price;
  private double weight;

  @DynamoDBHashKey(attributeName="ProductId") //partition key
  @DynamoDBAutoGeneratedKey
  public Integer getProductId() {
      return productId;
  }

  public void setProductId(Integer productId) {
      this.productId = productId;
  }
  @DynamoDBRangeKey(attributeName="ProductName") //sort key
  public String getProductName() {
      return productName;
  }
  public void setProductName(String productName) {
      this.productName = productName;
  }
  @DynamoDBAttribute(attributeName="Price")
  public double getPrice() {
      return price;
  }
  public void setPrice(double price) {
      this.price = price;
  }
  @DynamoDBAttribute(attributeName="Weight")
  public double getWeight() {
      return weight;
  }

  public void setWeight(double weight) {
      this.weight = weight;
  }

  @Override
  public String toString() {
      return "Product{" +
              "productId=" + productId +
              ", productName='" + productName + '\'' +
              ", price=" + price +
              ", weight=" + weight +
              '}';
  }
}
@DynamoDBTable(tableName = "Product") //make sure to give the same table name which you provide in AWS Console
public class Product {

  private int productId;
  private String productName;
  private double price;
  private double weight;

  @DynamoDBHashKey(attributeName="ProductId") //partition key
  @DynamoDBAutoGeneratedKey
  public Integer getProductId() {
      return productId;
  }

  public void setProductId(Integer productId) {
      this.productId = productId;
  }
  @DynamoDBRangeKey(attributeName="ProductName") //sort key
  public String getProductName() {
      return productName;
  }
  public void setProductName(String productName) {
      this.productName = productName;
  }
  @DynamoDBAttribute(attributeName="Price")
  public double getPrice() {
      return price;
  }
  public void setPrice(double price) {
      this.price = price;
  }
  @DynamoDBAttribute(attributeName="Weight")
  public double getWeight() {
      return weight;
  }

  public void setWeight(double weight) {
      this.weight = weight;
  }

  @Override
  public String toString() {
      return "Product{" +
              "productId=" + productId +
              ", productName='" + productName + '\'' +
              ", price=" + price +
              ", weight=" + weight +
              '}';
  }
}

Put an Item

To write a single item into the DynamoDB table. This will use the save method.

package com.dynamoDbDemo.controller;
import com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBMapper;
import com.dynamoDbDemo.entity.Product;
import org.springframework.beans.factory.annotation.Autowired;

public class ProductController {
  @Autowired
  private DynamoDBMapper dynamoDBMapper;
  //add an item
  void saveProduct() {
      Product item = new Product();
      item.setProductId(01) ;
      item.setProductName("Product 01");
      item.setPrice(50.5);
      item.setWeight(80.0);
      dynamoDBMapper.save(item);
  }
}
package com.dynamoDbDemo.controller;
import com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBMapper;
import com.dynamoDbDemo.entity.Product;
import org.springframework.beans.factory.annotation.Autowired;

public class ProductController {
  @Autowired
  private DynamoDBMapper dynamoDBMapper;
  //add an item
  void saveProduct() {
      Product item = new Product();
      item.setProductId(01) ;
      item.setProductName("Product 01");
      item.setPrice(50.5);
      item.setWeight(80.0);
      dynamoDBMapper.save(item);
  }
}

Get an Item

To get a single item from DynamoDB using Partition Key/hash key(ProductId) or the range key. This will use the load method.

Parameters for the load methods are

• class: The class to load, same as the DynamoDB table
• hashKey: The key of the object.
• rangeKey: The range key of the object(optional)
• config: The service call to fetch the object from DynamoDB is configured.

void getProductById(){
   //get a product item by Id
  dynamoDBMapper.load(Product.class,01);
}
void getProductById(){
   //get a product item by Id
  dynamoDBMapper.load(Product.class,01);
}

Update an Item

To update an item, 1st you will get the item that needs to be updated by the hash key/partition key(productId) and then you can update an item.

void update(){
   //get the product to update
  Product getItemToUpdate = dynamoDBMapper.load(Product.class,01);
  //Updating the product price from 50.5 to 85.0
  getItemToUpdate.setPrice(85.0);
  //Updating the product weight from 80.0 to 100.0
  getItemToUpdate.setWeight(100.0);
  dynamoDBMapper.save(getItemToUpdate);
}
void update(){
   //get the product to update
  Product getItemToUpdate = dynamoDBMapper.load(Product.class,01);
  //Updating the product price from 50.5 to 85.0
  getItemToUpdate.setPrice(85.0);
  //Updating the product weight from 80.0 to 100.0
  getItemToUpdate.setWeight(100.0);
  dynamoDBMapper.save(getItemToUpdate);
}

Batch Put Item

To write/put a batch of items into the DynamoDB table, you can use the batchSave method. The batchSave method of DynamoDBMapper is implemented using the BatchWriteItem API.

The below code is to write/put a batch of items into the Product DynamoDB table.

void batchAdd(){
  Product item1 = new Product();
  item1.setProductId(02) ;
  item1.setProductName("Product 02");
  item1.setPrice(50.0);
  item1.setWeight(80.5);

  Product item2 = new Product();
  item2.setProductId(03) ;
  item2.setProductName("Product 03");
  item2.setPrice(60.0);
  item2.setWeight(89.5);

  Product item3 = new Product();
  item3.setProductId(04) ;
  item3.setProductName("Product 04");
  item3.setPrice(67.0);
  item3.setWeight(56.5);
  dynamoDBMapper.batchSave(Arrays.asList(item1, item2, item3));
}
void batchAdd(){
  Product item1 = new Product();
  item1.setProductId(02) ;
  item1.setProductName("Product 02");
  item1.setPrice(50.0);
  item1.setWeight(80.5);

  Product item2 = new Product();
  item2.setProductId(03) ;
  item2.setProductName("Product 03");
  item2.setPrice(60.0);
  item2.setWeight(89.5);

  Product item3 = new Product();
  item3.setProductId(04) ;
  item3.setProductName("Product 04");
  item3.setPrice(67.0);
  item3.setWeight(56.5);
  dynamoDBMapper.batchSave(Arrays.asList(item1, item2, item3));
}

Batch Put Item & Delete

You can use BatchWriteItem to write or delete multiple items across multiple tables.

The below code is to write/put a batch of items into purchase and transaction tables and delete an item from the Product table. The primary key of the Purchase table consists of the PurchaseId and Quantity, PurchaseDate fields. The primary key of the ProductCategory table consists of the CategoryId and CategoryName fields.

void batchWrite(){
  // product Categories to save
  ProductCategory productCategoryItem = new ProductCategory();
  productCategoryItem.setCategoryId("01");
  productCategoryItem.setCategoryName("Category 01");
  productCategoryItem.setCategoryId("02");
  productCategoryItem.setCategoryName("Category 02");

  //  purchase item to save
  Purchase purchaseItem = new Purchase();
  purchaseItem.setPurchaseId(01);
  purchaseItem.setQuantity(02);
  purchaseItem.setPurchaseDate(dateNow);

  // Load Product  to delete
  Product product4 = dynamoDBMapper.load(Product.class, 04);

  List<Object> objectsToWrite = Arrays.asList(productCategoryItem, purchaseItem);
  List<Product> objectsToDelete = Arrays.asList(product4);
  dynamoDBMapper.batchWrite(objectsToWrite, objectsToDelete);
}
void batchWrite(){
  // product Categories to save
  ProductCategory productCategoryItem = new ProductCategory();
  productCategoryItem.setCategoryId("01");
  productCategoryItem.setCategoryName("Category 01");
  productCategoryItem.setCategoryId("02");
  productCategoryItem.setCategoryName("Category 02");

  //  purchase item to save
  Purchase purchaseItem = new Purchase();
  purchaseItem.setPurchaseId(01);
  purchaseItem.setQuantity(02);
  purchaseItem.setPurchaseDate(dateNow);

  // Load Product  to delete
  Product product4 = dynamoDBMapper.load(Product.class, 04);

  List<Object> objectsToWrite = Arrays.asList(productCategoryItem, purchaseItem);
  List<Product> objectsToDelete = Arrays.asList(product4);
  dynamoDBMapper.batchWrite(objectsToWrite, objectsToDelete);
}

It has a maximum write limit of 16MB and a maximum request limit of 25. Item updates are not possible with batch writes. In a batch, if there are two PutItem requests and one DeleteItem request, the failure of the PutItem request has no effect on the others.

Batch Get Items

To get a set of items from DynamoDB using Partition Key/hash key(ProductId) from one or more tables. This will use the batchload method.

void batchGet(){
  ArrayList<Object> itemsToGet = new ArrayList<Object>();

  Product productItem = new Product();
  productItem.setWeight(89.0);
  productItem.setPrice(67.0);
  productItem.setProductName("Product 05");
  productItem.setProductId(05);

  itemsToGet.add(productItem);

  ProductCategory productCategoryItem = new ProductCategory();
  productCategoryItem.setCategoryId("04");
  productCategoryItem.setCategoryName("Product Category 04");
  itemsToGet.add(productCategoryItem);

  Map<String, List<Object>> items = dynamoDBMapper.batchLoad(itemsToGet);
}
void batchGet(){
  ArrayList<Object> itemsToGet = new ArrayList<Object>();

  Product productItem = new Product();
  productItem.setWeight(89.0);
  productItem.setPrice(67.0);
  productItem.setProductName("Product 05");
  productItem.setProductId(05);

  itemsToGet.add(productItem);

  ProductCategory productCategoryItem = new ProductCategory();
  productCategoryItem.setCategoryId("04");
  productCategoryItem.setCategoryName("Product Category 04");
  itemsToGet.add(productCategoryItem);

  Map<String, List<Object>> items = dynamoDBMapper.batchLoad(itemsToGet);
}

Scan with Filter

You can use the scan method to scan through the entire table by using the FilterExpression operation you can filter out the results. To filter the results you can not use the partition or sort key.

void scanFilter(){
  HashMap<String, AttributeValue> eav = new HashMap<String, AttributeValue>();
  eav.put(":v1", new AttributeValue().withS("Product"));

  DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
          //Filter Expression
          .withFilterExpression("begins_with(ProductName,:v1)")
          .withExpressionAttributeValues(eav);

  List<Product> products =  dynamoDBMapper.scan(Product.class, scanExpression);
}
void scanFilter(){
  HashMap<String, AttributeValue> eav = new HashMap<String, AttributeValue>();
  eav.put(":v1", new AttributeValue().withS("Product"));

  DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
          //Filter Expression
          .withFilterExpression("begins_with(ProductName,:v1)")
          .withExpressionAttributeValues(eav);

  List<Product> products =  dynamoDBMapper.scan(Product.class, scanExpression);
}

Note: Scan performs better with small tables with fewer filters.

Scan Parallel

The parallel scan will be splitting tables into parts logically then "workers" scan segments in parallel. This is the quick fix if you want to scan larger amounts of tables. You can define the number of workers/Segments.

The below code is to scan parallel in the Purchase table.

void scanParallel(){
  int numberOfWorkers = 3;

  Map<String, AttributeValue> eav = new HashMap<String, AttributeValue>();
  eav.put(":v", new AttributeValue().withN("90"));

  DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
          //Filter Expression
          .withFilterExpression("Quantity <= :v")
          .withExpressionAttributeValues(eav);

  List<Purchase> scanParallelResult = dynamoDBMapper.parallelScan(Purchase.class, scanExpression, numberOfWorkers);
}
void scanParallel(){
  int numberOfWorkers = 3;

  Map<String, AttributeValue> eav = new HashMap<String, AttributeValue>();
  eav.put(":v", new AttributeValue().withN("90"));

  DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
          //Filter Expression
          .withFilterExpression("Quantity <= :v")
          .withExpressionAttributeValues(eav);

  List<Purchase> scanParallelResult = dynamoDBMapper.parallelScan(Purchase.class, scanExpression, numberOfWorkers);
}

Query

You should use a query operation to get a lookup to a certain partition. To query the table there should be a sort key along with the partition key (primary key). The query is quicker and cheaper than the scan.

The primary key of the ProductCategory table consists of the CategoryId and CategoryName(sort key). You can fetch up to 1MB of records.

void query(){
  Map<String, AttributeValue> eav = new HashMap<String, AttributeValue>();
  eav.put(":v1",new AttributeValue().withS("01"));
  eav.put(":v2", new AttributeValue().withS("Category 01"));

  DynamoDBQueryExpression<ProductCategory> queryExpression = new DynamoDBQueryExpression<ProductCategory>()
          .withKeyConditionExpression("CategoryId = :v1 and CategoryName= :v2")
          .withExpressionAttributeValues(eav);
  List<ProductCategory> latestReplies = dynamoDBMapper.query(ProductCategory.class,queryExpression);

}
void query(){
  Map<String, AttributeValue> eav = new HashMap<String, AttributeValue>();
  eav.put(":v1",new AttributeValue().withS("01"));
  eav.put(":v2", new AttributeValue().withS("Category 01"));

  DynamoDBQueryExpression<ProductCategory> queryExpression = new DynamoDBQueryExpression<ProductCategory>()
          .withKeyConditionExpression("CategoryId = :v1 and CategoryName= :v2")
          .withExpressionAttributeValues(eav);
  List<ProductCategory> latestReplies = dynamoDBMapper.query(ProductCategory.class,queryExpression);

}

Delete an Item

Deleting a single item from the DynamoDB table. You can use the delete method to delete an item.

void deleteItem(){
  //get the product to delete
  Product getItemToDelete = dynamoDBMapper.load(Product.class,01);
  //delete the item
  dynamoDBMapper.delete(getItemToDelete);
}
void deleteItem(){
  //get the product to delete
  Product getItemToDelete = dynamoDBMapper.load(Product.class,01);
  //delete the item
  dynamoDBMapper.delete(getItemToDelete);
}

Batch Delete Items

To delete a batch of items from one or more DynamoDB tables. You can use the batchDelete method.

void batchDelete(){
  //get the products to delete
  Product getItem1ToDelete = dynamoDBMapper.load(Product.class,02);
  Product getItem2ToDelete = dynamoDBMapper.load(Product.class,03);

//delete the items
  dynamoDBMapper.batchDelete(Arrays.asList(getItem1ToDelete,getItem2ToDelete));
}
void batchDelete(){
  //get the products to delete
  Product getItem1ToDelete = dynamoDBMapper.load(Product.class,02);
  Product getItem2ToDelete = dynamoDBMapper.load(Product.class,03);

//delete the items
  dynamoDBMapper.batchDelete(Arrays.asList(getItem1ToDelete,getItem2ToDelete));
}

Delete a table

To delete a table, go to the AWS console and select Tables from the navigation pane, then from the table list, select the table you want to delete.

You can use the code below to delete a table.

AmazonDynamoDBClient client = new AmazonDynamoDBClient()
    .withEndpoint("http://localhost:8000");
try {
 DynamoDB dynamoDB = new DynamoDB(client);
 Table table = dynamoDB.getTable("Product");
 table.delete();
} catch (Exception e){
 System.err.println(e.getMessage());
}
AmazonDynamoDBClient client = new AmazonDynamoDBClient()
    .withEndpoint("http://localhost:8000");
try {
 DynamoDB dynamoDB = new DynamoDB(client);
 Table table = dynamoDB.getTable("Product");
 table.delete();
} catch (Exception e){
 System.err.println(e.getMessage());
}

Run DynamoDB Local

If you need to use DynamoDB offline locally, you can use DynamoDB locally distributed by AWS or DynamoDB from localstack

1. First, install version 6. x or higher of the Java Runtime Environment (JRE) and obtain DynamoDB from here.

2. After that, extract the archive and copy its contents to a location Finally, open a terminal in the location where you extracted the files and run the below command.