Package software.amazon.awssdk.enhanced.dynamodb

Interface DynamoDbTable<T>

Type Parameters:
T - The type of the modelled object.
All Superinterfaces:
MappedTableResource<T>
All Known Implementing Classes:
DefaultDynamoDbTable
@ThreadSafe public interface DynamoDbTable<T> extends MappedTableResource<T>
Synchronous interface for running commands against an object that is linked to a specific DynamoDb table resource and therefore knows how to map records from that table into a modelled object.

By default, all command methods throw an UnsupportedOperationException to prevent interface extensions from breaking implementing classes.

  • Method Details

    • index

      DynamoDbIndex<T> index(String indexName)
      Returns a mapped index that can be used to execute commands against a secondary index belonging to the table being mapped by this object. Note that only a subset of the commands that work against a table will work against a secondary index.
      Parameters:
      indexName - The name of the secondary index to build the command interface for.
      Returns:
      A DynamoDbIndex object that can be used to execute database commands against.

    • createTable

      default void createTable(CreateTableEnhancedRequest request)
      Creates a new table in DynamoDb with the name and schema already defined for this DynamoDbTable together with additional parameters specified in the supplied request object, CreateTableEnhancedRequest.

      Use DynamoDbEnhancedClient.table(String, TableSchema) to define the mapped table resource.

      This operation calls the low-level DynamoDB API CreateTable operation. Note that this is an asynchronous operation and that the table may not immediately be available for writes and reads. You can use DynamoDbWaiter.waitUntilTableExists(DescribeTableRequest) to wait for the resource to be ready.

      Example: 

       

 ProvisionedThroughput provisionedThroughput = ProvisionedThroughput.builder()
                                                                    .readCapacityUnits(50L)
                                                                    .writeCapacityUnits(50L)
                                                                    .build();
 mappedTable.createTable(CreateTableEnhancedRequest.builder()
                                                   .provisionedThroughput(provisionedThroughput)
                                                   .build());

 dynamoDbClient.waiter().waitUntilTableExists(b -> b.tableName(tableName));
      Parameters:
      request - A CreateTableEnhancedRequest containing optional parameters for table creation.

    • createTable

      default void createTable(Consumer<CreateTableEnhancedRequest.Builder> requestConsumer)
      Creates a new table in DynamoDb with the name and schema already defined for this DynamoDbTable together with additional parameters specified in the supplied request object, CreateTableEnhancedRequest.

      Use DynamoDbEnhancedClient.table(String, TableSchema) to define the mapped table resource.

      This operation calls the low-level DynamoDB API CreateTable operation. Note that this is an asynchronous operation and that the table may not immediately be available for writes and reads. You can use DynamoDbWaiter.waitUntilTableExists(DescribeTableRequest) to wait for the resource to be ready.

      Note: This is a convenience method that creates an instance of the request builder avoiding the need to create one manually via CreateTableEnhancedRequest.builder().

      Example: 

       

 ProvisionedThroughput provisionedThroughput = ProvisionedThroughput.builder()
                                                                    .readCapacityUnits(50L)
                                                                    .writeCapacityUnits(50L)
                                                                    .build();
 mappedTable.createTable(r -> r.provisionedThroughput(provisionedThroughput));
 dynamoDbClient.waiter().waitUntilTableExists(b -> b.tableName(tableName));
      Parameters:
      requestConsumer - A Consumer of CreateTableEnhancedRequest.Builder containing optional parameters for table creation.

    • createTable

      default void createTable()
      Creates a new table in DynamoDb with the name and schema already defined for this DynamoDbTable.

      Use DynamoDbEnhancedClient.table(String, TableSchema) to define the mapped table resource.

      This operation calls the low-level DynamoDB API CreateTable operation. Note that this is an asynchronous operation and that the table may not immediately be available for writes and reads. You can use DynamoDbWaiter.waitUntilTableExists(DescribeTableRequest) to wait for the resource to be ready.

      Example: 

       

 mappedTable.createTable();
 dynamoDbClient.waiter().waitUntilTableExists(b -> b.tableName(tableName));

    • deleteItem

      default T deleteItem(DeleteItemEnhancedRequest request)
      Deletes a single item from the mapped table using a supplied primary Key.

      The additional configuration parameters that the enhanced client supports are defined in the DeleteItemEnhancedRequest.

      This operation calls the low-level DynamoDB API DeleteItem operation. Consult the DeleteItem documentation for further details and constraints.

      Example: 

       

 MyItem previouslyPersistedItem = mappedTable.delete(DeleteItemEnhancedRequest.builder().key(key).build());
      Parameters:
      request - A DeleteItemEnhancedRequest with key and optional directives for deleting an item from the table.
      Returns:
      The item that was persisted in the database before it was deleted.

    • deleteItem

      default T deleteItem(Consumer<DeleteItemEnhancedRequest.Builder> requestConsumer)
      Deletes a single item from the mapped table using a supplied primary Key.

      The additional configuration parameters that the enhanced client supports are defined in the DeleteItemEnhancedRequest.

      This operation calls the low-level DynamoDB API DeleteItem operation. Consult the DeleteItem documentation for further details and constraints.

      Note: This is a convenience method that creates an instance of the request builder avoiding the need to create one manually via DeleteItemEnhancedRequest.builder().

      Example: 

       

 MyItem previouslyPersistedItem = mappedTable.delete(r -> r.key(key));
      Parameters:
      requestConsumer - A Consumer of DeleteItemEnhancedRequest with key and optional directives for deleting an item from the table.
      Returns:
      The item that was persisted in the database before it was deleted.

    • deleteItem

      default T deleteItem(Key key)
      Deletes a single item from the mapped table using a supplied primary Key.

      This operation calls the low-level DynamoDB API DeleteItem operation. Consult the DeleteItem documentation for further details and constraints.

      Example: 

       

 MyItem previouslyPersistedItem = mappedTable.delete(key);
      Parameters:
      key - A Key that will be used to match a specific record to delete from the database table.
      Returns:
      The item that was persisted in the database before it was deleted.

    • deleteItem

      default T deleteItem(T keyItem)
      Deletes a single item from the mapped table using just the key of a supplied modelled 'key item' object.

      This operation calls the low-level DynamoDB API DeleteItem operation. Consult the DeleteItem documentation for further details and constraints.

      Example: 

       

 MyItem previouslyPersistedItem = mappedTable.deleteItem(keyItem);
      Parameters:
      keyItem - A modelled item with the primary key fields set that will be used to match a specific record to delete from the database table.
      Returns:
      The item that was persisted in the database before it was deleted.

    • deleteItemWithResponse

      default DeleteItemEnhancedResponse<T> deleteItemWithResponse(DeleteItemEnhancedRequest request)
      Deletes a single item from the mapped table using a supplied primary Key.

      The additional configuration parameters that the enhanced client supports are defined in the DeleteItemEnhancedRequest.

      This operation calls the low-level DynamoDB API DeleteItem operation. Consult the DeleteItem documentation for further details and constraints. Unlike deleteItem(DeleteItemEnhancedRequest), this returns a response object, allowing the user to retrieve additional information from DynamoDB related to the API call, such as ConsumedCapacity if specified on the request.

      Example: 

       

 DeleteItemEnhancedRequest request = DeleteItemEnhancedRequest.builder().key(key).build();
 DeleteItemEnhancedResponse<MyItem> response = mappedTable.deleteItemWithResponse(request);
      Parameters:
      request - A DeleteItemEnhancedRequest with key and optional directives for deleting an item from the table.
      Returns:
      The response returned by DynamoDB.

    • deleteItemWithResponse

      default DeleteItemEnhancedResponse<T> deleteItemWithResponse(Consumer<DeleteItemEnhancedRequest.Builder> requestConsumer)
      Deletes a single item from the mapped table using a supplied primary Key.

      The additional configuration parameters that the enhanced client supports are defined in the DeleteItemEnhancedRequest.

      This operation calls the low-level DynamoDB API DeleteItem operation. Consult the DeleteItem documentation for further details and constraints. Unlike deleteItem(Consumer), this returns a response object, allowing the user to retrieve additional information from DynamoDB related to the API call, such as ConsumedCapacity if specified on the request.

      Note: This is a convenience method that creates an instance of the request builder avoiding the need to create one manually via DeleteItemEnhancedRequest.builder().

      Example: 

       

 DeleteItemEnhancedResponse<MyItem> response = mappedTable.deleteWithResponse(r -> r.key(key));
      Parameters:
      requestConsumer - A Consumer of DeleteItemEnhancedRequest with key and optional directives for deleting an item from the table.
      Returns:
      The response returned by DynamoDB.

    • getItem

      default T getItem(GetItemEnhancedRequest request)
      Retrieves a single item from the mapped table using a supplied primary Key.

      The additional configuration parameters that the enhanced client supports are defined in the GetItemEnhancedRequest.

      This operation calls the low-level DynamoDB API GetItem operation. Consult the GetItem documentation for further details and constraints.

      Example: 

       

 MyItem item = mappedTable.getItem(GetItemEnhancedRequest.builder().key(key).build());
      Parameters:
      request - A GetItemEnhancedRequest with key and optional directives for retrieving an item from the table.
      Returns:
      The retrieved item

    • getItem

      default T getItem(Consumer<GetItemEnhancedRequest.Builder> requestConsumer)
      Retrieves a single item from the mapped table using a supplied primary Key.

      The additional configuration parameters that the enhanced client supports are defined in the GetItemEnhancedRequest.

      This operation calls the low-level DynamoDB API GetItem operation. Consult the GetItem documentation for further details and constraints.

      Note: This is a convenience method that creates an instance of the request builder avoiding the need to create one manually via GetItemEnhancedRequest.builder().

      Example: 

       

 MyItem item = mappedTable.getItem(r -> r.key(key));
      Parameters:
      requestConsumer - A Consumer of GetItemEnhancedRequest.Builder with key and optional directives for retrieving an item from the table.
      Returns:
      The retrieved item

    • getItem

      default T getItem(Key key)
      Retrieves a single item from the mapped table using a supplied primary Key.

      This operation calls the low-level DynamoDB API GetItem operation. Consult the GetItem documentation for further details and constraints.

      Example: 

       

 MyItem item = mappedTable.getItem(key);
      Parameters:
      key - A Key that will be used to match a specific record to retrieve from the database table.
      Returns:
      The retrieved item

    • getItem

      default T getItem(T keyItem)
      Retrieves a single item from the mapped table using just the key of a supplied modelled 'key item'.

      This operation calls the low-level DynamoDB API GetItem operation. Consult the GetItem documentation for further details and constraints.

      Example: 

       

 MyItem item = mappedTable.getItem(keyItem);
      Parameters:
      keyItem - A modelled item with the primary key fields set that will be used to match a specific record to retrieve from the database table.
      Returns:
      The retrieved item

    • getItemWithResponse

      default GetItemEnhancedResponse<T> getItemWithResponse(GetItemEnhancedRequest request)
      Retrieves a single item from the mapped table using a supplied primary Key. This is similar to getItem(GetItemEnhancedRequest) but returns GetItemEnhancedResponse for additional information.

      The additional configuration parameters that the enhanced client supports are defined in the GetItemEnhancedRequest.

      This operation calls the low-level DynamoDB API GetItem operation. Consult the GetItem documentation for further details and constraints.

      Example: 

       

 MyItem item = mappedTable.getItemWithResponse(GetItemEnhancedRequest.builder().key(key).build());
      Parameters:
      request - A GetItemEnhancedRequest with key and optional directives for retrieving an item from the table.
      Returns:
      The retrieved item

    • getItemWithResponse

      default GetItemEnhancedResponse<T> getItemWithResponse(Consumer<GetItemEnhancedRequest.Builder> requestConsumer)
      Retrieves a single item from the mapped table using a supplied primary Key. This is similar to getItem(Consumer<GetItemEnhancedRequest.Builder>) but returns GetItemEnhancedResponse for additional information.

      The additional configuration parameters that the enhanced client supports are defined in the GetItemEnhancedRequest.

      This operation calls the low-level DynamoDB API GetItem operation. Consult the GetItem documentation for further details and constraints.

      Note: This is a convenience method that creates an instance of the request builder avoiding the need to create one manually via GetItemEnhancedRequest.builder().

      Example: 

       

 MyItem item = mappedTable.getItemWithResponse(r -> r.key(key));
      Parameters:
      requestConsumer - A Consumer of GetItemEnhancedRequest.Builder with key and optional directives for retrieving an item from the table.
      Returns:
      The retrieved item

    • query

      default PageIterable<T> query(QueryEnhancedRequest request)
      Executes a query against the primary index of the table using a QueryConditional expression to retrieve a list of items matching the given conditions.

      The result can be accessed either through iterable Pages or Page.items() directly. If you are iterating the pages, the result is accessed through iterable pages (see Page) in an interactive way; each time a result page is retrieved, a query call is made to DynamoDb to get those entries. If no matches are found, the resulting iterator will contain an empty page. Results are sorted by sort key value in ascending order by default; this behavior can be overridden in the QueryEnhancedRequest.

      The additional configuration parameters that the enhanced client supports are defined in the QueryEnhancedRequest.

      This operation calls the low-level DynamoDB API Query operation. Consult the Query documentation for further details and constraints.

      Example:

      1) Iterating through pages 

       
 QueryConditional queryConditional = QueryConditional.keyEqualTo(Key.builder().partitionValue("id-value").build());
 PageIterable<MyItem> results = table.query(QueryEnhancedRequest.builder()
                                                                        .queryConditional(queryConditional)
                                                                        .build());
 results.stream().forEach(p -> p.items().forEach(item -> System.out.println(item)))
      2) Iterating through items 
       
 results.items().stream().forEach(item -> System.out.println(item));
      Parameters:
      request - A QueryEnhancedRequest defining the query conditions and how to handle the results.
      Returns:
      an iterator of type SdkIterable with paginated results (see Page).
      See Also:

    • query

      default PageIterable<T> query(Consumer<QueryEnhancedRequest.Builder> requestConsumer)
      This is a convenience method that creates an instance of the request builder avoiding the need to create one manually via QueryEnhancedRequest.builder().

      Example: 

       

 PageIterable<MyItem> results =
     mappedTable.query(r -> r.queryConditional(QueryConditional.keyEqualTo(k -> k.partitionValue("id-value"))));
      Parameters:
      requestConsumer - A Consumer of QueryEnhancedRequest defining the query conditions and how to handle the results.
      Returns:
      an iterator of type SdkIterable with paginated results (see Page).
      See Also:

    • query

      default PageIterable<T> query(QueryConditional queryConditional)
      Executes a query against the primary index of the table using a QueryConditional expression to retrieve a list of items matching the given conditions.

      Example: 

       

 PageIterable<MyItem> results =
     mappedTable.query(QueryConditional.keyEqualTo(Key.builder().partitionValue("id-value").build()));
      Parameters:
      queryConditional - A QueryConditional defining the matching criteria for records to be queried.
      Returns:
      an iterator of type SdkIterable with paginated results (see Page).
      See Also:

    • putItem

      default void putItem(PutItemEnhancedRequest<T> request)
      Puts a single item in the mapped table. If the table contains an item with the same primary key, it will be replaced with this item.

      The additional configuration parameters that the enhanced client supports are defined in the PutItemEnhancedRequest.

      This operation calls the low-level DynamoDB API PutItem operation. Consult the PutItem documentation for further details and constraints.

      Example: 

       

 mappedTable.putItem(PutItemEnhancedRequest.builder(MyItem.class).item(item).build());
      Parameters:
      request - A PutItemEnhancedRequest that includes the item to enter into the table, its class and optional directives.

    • putItem

      default void putItem(Consumer<PutItemEnhancedRequest.Builder<T>> requestConsumer)
      Puts a single item in the mapped table. If the table contains an item with the same primary key, it will be replaced with this item.

      The additional configuration parameters that the enhanced client supports are defined in the PutItemEnhancedRequest.

      This operation calls the low-level DynamoDB API PutItem operation. Consult the PutItem documentation for further details and constraints.

      Example: 

       

 mappedTable.putItem(r -> r.item(item));
      Parameters:
      requestConsumer - A Consumer of PutItemEnhancedRequest.Builder that includes the item to enter into the table, its class and optional directives.

    • putItem

      default void putItem(T item)
      Puts a single item in the mapped table. If the table contains an item with the same primary key, it will be replaced with this item.

      This operation calls the low-level DynamoDB API PutItem operation. Consult the PutItem documentation for further details and constraints.

      Example: 

       

 mappedTable.putItem(item);
      Parameters:
      item - the modelled item to be inserted into or overwritten in the database table.

    • putItemWithResponse

      default PutItemEnhancedResponse<T> putItemWithResponse(PutItemEnhancedRequest<T> request)
      Puts a single item in the mapped table. If the table contains an item with the same primary key, it will be replaced with this item. This is similar to putItem(PutItemEnhancedRequest) but returns PutItemEnhancedResponse for additional information.

      The additional configuration parameters that the enhanced client supports are defined in the PutItemEnhancedRequest.

      This operation calls the low-level DynamoDB API PutItem operation. Consult the PutItem documentation for further details and constraints.

      Example: 

       

 mappedTable.putItem(PutItemEnhancedRequest.builder(MyItem.class).item(item).build());
      Parameters:
      request - A PutItemEnhancedRequest that includes the item to enter into the table, its class and optional directives.
      Returns:
      The response returned by DynamoDB.

    • putItemWithResponse

      default PutItemEnhancedResponse<T> putItemWithResponse(Consumer<PutItemEnhancedRequest.Builder<T>> requestConsumer)
      Puts a single item in the mapped table. If the table contains an item with the same primary key, it will be replaced with this item. This is similar to putItem(PutItemEnhancedRequest) but returns PutItemEnhancedResponse for additional information.

      The additional configuration parameters that the enhanced client supports are defined in the PutItemEnhancedRequest.

      This operation calls the low-level DynamoDB API PutItem operation. Consult the PutItem documentation for further details and constraints.

      Example: 

       

 mappedTable.putItem(PutItemEnhancedRequest.builder(MyItem.class).item(item).build());
      Parameters:
      requestConsumer - A Consumer of PutItemEnhancedRequest.Builder that includes the item to enter into the table, its class and optional directives.
      Returns:
      The response returned by DynamoDB.

    • scan

      default PageIterable<T> scan(ScanEnhancedRequest request)
      Scans the table and retrieves all items.

      The result can be accessed either through iterable Pages or items across all pages directly. Each time a result page is retrieved, a query call is made to DynamoDb to get those entries. If no matches are found, the resulting iterator will contain an empty page.

      The additional configuration parameters that the enhanced client supports are defined in the ScanEnhancedRequest.

      Example:

      1) Iterating through pages 

       

 PageIterable<MyItem> results = mappedTable.scan(ScanEnhancedRequest.builder().consistentRead(true).build());
 results.stream().forEach(p -> p.items().forEach(item -> System.out.println(item)))

      2) Iterating through items 

       

 PageIterable<MyItem> results = mappedTable.scan(ScanEnhancedRequest.builder().consistentRead(true).build());
 results.items().stream().forEach(item -> System.out.println(item));
      Parameters:
      request - A ScanEnhancedRequest defining how to handle the results.
      Returns:
      an iterator of type SdkIterable with paginated results (see Page).
      See Also:

    • scan

      default PageIterable<T> scan(Consumer<ScanEnhancedRequest.Builder> requestConsumer)
      This is a convenience method that creates an instance of the request builder avoiding the need to create one manually via ScanEnhancedRequest.builder().

      Example: 

       

 PageIterable<MyItem> results = mappedTable.scan(r -> r.limit(5));
      Parameters:
      requestConsumer - A Consumer of ScanEnhancedRequest defining the query conditions and how to handle the results.
      Returns:
      an iterator of type SdkIterable with paginated results (see Page).
      See Also:

    • scan

      default PageIterable<T> scan()
      Scans the table and retrieves all items using default settings.

      The result can be accessed either through iterable Pages or items across all pages directly. Each time a result page is retrieved, a query call is made to DynamoDb to get those entries. If no matches are found, the resulting iterator will contain an empty page.

      Example: 

       

 PageIterable<MyItem> results = mappedTable.scan();
      Returns:
      an iterator of type SdkIterable with paginated results (see Page).
      See Also:

    • updateItem

      default T updateItem(UpdateItemEnhancedRequest<T> request)
      Updates an item in the mapped table, or adds it if it doesn't exist.

      The additional configuration parameters that the enhanced client supports are defined in the UpdateItemEnhancedRequest.

      This operation calls the low-level DynamoDB API UpdateItem operation. Consult the UpdateItem documentation for further details and constraints.

      Example: 

       

 MyItem item = mappedTable.updateItem(UpdateItemEnhancedRequest.builder(MyItem.class).item(item).build());
      Parameters:
      request - A UpdateItemEnhancedRequest that includes the item to be updated, its class and optional directives.
      Returns:
      The updated item

    • updateItem

      default T updateItem(Consumer<UpdateItemEnhancedRequest.Builder<T>> requestConsumer)
      Updates an item in the mapped table, or adds it if it doesn't exist.

      The additional configuration parameters that the enhanced client supports are defined in the UpdateItemEnhancedRequest.

      This operation calls the low-level DynamoDB API UpdateItem operation. Consult the UpdateItem documentation for further details and constraints.

      Example: 

       

 MyItem item = mappedTable.updateItem(r -> r.item(item));
      Parameters:
      requestConsumer - A Consumer of UpdateItemEnhancedRequest.Builder that includes the item to be updated, its class and optional directives.
      Returns:
      The updated item

    • updateItem

      default T updateItem(T item)
      Updates an item in the mapped table, or adds it if it doesn't exist.

      This operation calls the low-level DynamoDB API UpdateItem operation. Consult the UpdateItem documentation for further details and constraints.

      Example: 

       

 MyItem item = mappedTable.updateItem(item);
      Parameters:
      item - the modelled item to be inserted into or updated in the database table.
      Returns:
      The updated item

    • updateItemWithResponse

      default UpdateItemEnhancedResponse<T> updateItemWithResponse(UpdateItemEnhancedRequest<T> request)
      Updates an item in the mapped table, or adds it if it doesn't exist. This is similar to updateItem(UpdateItemEnhancedRequest)} but returns UpdateItemEnhancedResponse for additional information.

      This operation calls the low-level DynamoDB API UpdateItem operation. Consult the UpdateItem documentation for further details and constraints.

      Example: 

       
 UpdateItemEnhancedRequest<MyItem> request = UpdateItemEnhancedRequest.builder(MyItem.class).item(myItem).build();
 UpdateItemEnhancedResponse<MyItem> response = mappedTable.updateItemWithResponse(request);

      Parameters:
      request - the modelled item to be inserted into or updated in the database table.
      Returns:
      The response returned by DynamoDB.

    • updateItemWithResponse

      default UpdateItemEnhancedResponse<T> updateItemWithResponse(Consumer<UpdateItemEnhancedRequest.Builder<T>> requestConsumer)
      Updates an item in the mapped table, or adds it if it doesn't exist. This is similar to updateItem(Consumer) but returns UpdateItemEnhancedResponse for additional information.

      This operation calls the low-level DynamoDB API UpdateItem operation. Consult the UpdateItem documentation for further details and constraints.

      Example: 

       

 UpdateItemEnhancedResponse<MyItem> response = mappedTable.updateItemWithResponse(r ->r.item(myItem));

      Parameters:
      requestConsumer - A Consumer of UpdateItemEnhancedRequest.Builder that includes the item * to be updated, its class and optional directives.
      Returns:
      The response from DynamoDB.

    • deleteTable

      default void deleteTable()
      Deletes a table in DynamoDb with the name and schema already defined for this DynamoDbTable.

      Use DynamoDbEnhancedClient.table(String, TableSchema) to define the mapped table resource.

      This operation calls the low-level DynamoDB API DeleteTable operation. Note that this is an asynchronous operation and that the table may not immediately be deleted. You can use DynamoDbWaiter.waitUntilTableNotExists(software.amazon.awssdk.services.dynamodb.model.DescribeTableRequest) in the underlying client.

      Example: 

       

 mappedTable.deleteTable();

    • describeTable

      default DescribeTableEnhancedResponse describeTable()
      Describes a table in DynamoDb with the name defined for this DynamoDbTable. This operation calls the low-level DynamoDB API DescribeTable operation, see DynamoDbClient.describeTable(DescribeTableRequest)

      Example: 

       

 DescribeTableEnhancedResponse response = mappedTable.describeTable();