Get started using the Enhanced Document API

The Enhanced Document API requires the same dependencies that are needed for the DynamoDB Enhanced Client API. It also requires a DynamoDbEnhancedClient instance as shown at the start of this topic.

Because the Enhanced Document API was released with version 2.20.3 of the Amazon SDK for Java 2.x, you need that version or greater.

Create a DocumentTableSchema and a DynamoDbTable

To invoke commands against a DynamoDB table using the Enhanced Document API, associate the table with a client-side DynamoDbTable<EnhancedDocument> resource object.

The enhanced client's table() method creates a DynamoDbTable<EnhancedDocument> instance and requires parameters for the DynamoDB table name and a DocumentTableSchema.

The builder for a DocumentTableSchema requires a primary index key and one or more attribute converter providers. The AttributeConverterProvider.defaultProvider() method provides converters for default types. It should be specified even if you provide a custom attribute converter provider. You can add an optional secondary index key to the builder.

The following code snippet shows the code that generates the client-side representation of a DynamoDB person table that stores schemaless EnhancedDocument objects.

DynamoDbTable<EnhancedDocument> documentDynamoDbTable = 
                enhancedClient.table("person",
                        TableSchema.documentSchemaBuilder()
                            // Specify the primary key attributes.
                            .addIndexPartitionKey(TableMetadata.primaryIndexName(),"id", AttributeValueType.S)
                            .addIndexSortKey(TableMetadata.primaryIndexName(), "lastName", AttributeValueType.S)
                            // Specify attribute converter providers. Minimally add the default one.
                            .attributeConverterProviders(AttributeConverterProvider.defaultProvider())
                            .build());
                                                         
// Call documentTable.createTable() if "person" does not exist in DynamoDB.
// createTable() should be called only one time.

The following shows the JSON representation of a person object that is used throughout this section.

{
  "id": 1,
  "firstName": "Richard",
  "lastName": "Roe",
  "age": 25,
  "addresses":
    {
      "home": {
        "zipCode": "00000",
        "city": "Any Town",
        "state": "FL",
        "street": "123 Any Street"
      },
      "work": {
        "zipCode": "00001",
        "city": "Anywhere",
        "state": "FL",
        "street": "100 Main Street"
      }
    },
  "hobbies": [
    "Hobby 1",
    "Hobby 2"
  ],
  "phoneNumbers": [
    {
      "type": "Home",
      "number": "555-0100"
    },
    {
      "type": "Work",
      "number": "555-0119"
    }
  ]
}