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 expressions and conditions

Expressions in the DynamoDB Enhanced Client API are Java representations of DynamoDB expressions.

The DynamoDB Enhanced Client API uses three types of expressions:

Expression anatomy

An expression is made up of the following:

Use a builder to generate anExpression object that takes the following general form.

Expression expression = Expression.builder()
                            .expression(<String>)
                            .expressionNames(<Map>)
                            .expressionValues(<Map>)
                           .build()

Expressions usually require a map of expression values. The map provides the values for the placeholders in the string expression. The map key consists of the placeholder name preceded with a colon (:) and the map value is an instance of AttributeValue. The AttributeValues class has convenience methods to generate an AttributeValue instance from a literal. Alternatively, you can use the AttributeValue.Builder to generate an AttributeValue instance.

The following snippet shows a map with two entries after comment line 2. The string passed to the expression() method, shown after comment line 1, contains the placeholders that DynamoDB resolves before performing the operation. This snippet doesn't contain a map of expression names, because price is a permissible attribute name.

    public static void scanAsync(DynamoDbAsyncTable productCatalog) {
        ScanEnhancedRequest request = ScanEnhancedRequest.builder()
                .consistentRead(true)
                .attributesToProject("id", "title", "authors", "price")
                .filterExpression(Expression.builder()
                        // 1. :min_value and :max_value are placeholders for the values provided by the map
                        .expression("price >= :min_value AND price <= :max_value")
                        // 2. Two values are needed for the expression and each is supplied as a map entry.
                        .expressionValues(
                                Map.of( ":min_value", numberValue(8.00),
                                        ":max_value", numberValue(400_000.00)))
                        .build())
                .build();

If an attribute name in the DynamoDB table is a reserved word, begins with a number, or contains a space, a map of expression names is required for the Expression.

For example, if the attribute name was 1price instead of price in the previous code example, the example would need to be modified as shown in the following example.

        ScanEnhancedRequest request = ScanEnhancedRequest.builder()
                .filterExpression(Expression.builder()
                        .expression("#price >= :min_value AND #price <= :max_value")
                        .expressionNames( Map.of("#price", "1price") )
                        .expressionValues(
                                Map.of(":min_value", numberValue(8.00),
                                        ":max_value", numberValue(400_000.00)))
                        .build())
                .build();

A placeholder for an expression name begins with the pound sign (#). An entry for the map of expression names uses the placeholder as the key and the attribute name as the value. The map is added to the expression builder with the expressionNames() method. DynamoDB resolves the attribute name before it performs the operation.

Expression values are not required if a function is used in the string expression. An example of an expression function is attribute_exists(<attribute_name>).

The following example builds an Expression that uses a DynamoDB function. The expression string in this example uses no placeholders. This expression could be used on a putItem operation to check if an item already exists in the database with a movie attribute's value equal to the data object's movie attribute.

Expression exp = Expression.builder().expression("attribute_not_exists (movie)").build();

The DynamoDB Developer Guide contains complete information on the low-level expressions that are used with DynamoDB.

Condition expressions and conditionals

When you use the putItem(), updateItem(), and deleteItem() methods, and also when you use transaction and batch operations, you use Expression objects to specify conditions that DynamoDB must meet to proceed with the operation. These expressions are named condition expressions. For an example, see the condition expression used in the addDeleteItem() method (after comment line 1) of transaction example shown in this guide.

When you work with the query() methods, a condition is expressed as a QueryConditional. The QueryConditional class has several static convenience methods that help you write the criteria that determine which items to read from DynamoDB.

For examples of QueryConditionals, see the first code example of the Query method examples section of this guide.

Filter expressions

Filter expressions are used in scan and query operations to filter the items that are returned.

A filter expression is applied after all the data is read from the database, so the read cost is the same as if there were no filter. The Amazon DynamoDB Developer Guide has more information about using filter expressions for both query and scan operations.

The following example shows a filter expression added to a scan request. The criteria restricts the items returned to items with a price between 8.00 and 80.00 inclusive.

        Map<String, AttributeValue> expressionValues = Map.of(
                ":min_value", numberValue(8.00),
                ":max_value", numberValue(80.00));

        ScanEnhancedRequest request = ScanEnhancedRequest.builder()
                .consistentRead(true)
                // 1. the 'attributesToProject()' method allows you to specify which values you want returned.
                .attributesToProject("id", "title", "authors", "price")
                // 2. Filter expression limits the items returned that match the provided criteria.
                .filterExpression(Expression.builder()
                        .expression("price >= :min_value AND price <= :max_value")
                        .expressionValues(expressionValues)
                        .build())
                .build();

Update expressions

The DynamoDB Enhanced Client's updateItem() method provides a standard way to update items in DynamoDB. However, when you require more functionality, UpdateExpressions provide a type-safe representation of DynamoDB update expression syntax. For example, you can use UpdateExpressions to increase values without first reading items from DynamoDB, or add individual members to a list. Update expressions are currently available in custom extensions for the updateItem() method.

For an example that uses update expressions, see the custom extension example in this guide.

More information about update expressions is available in the Amazon DynamoDB Developer Guide.