Menu
Amazon DynamoDB
Developer Guide (API Version 2012-08-10)

Performing Conditional Writes with Condition Expressions

To find items in a table, you use operations such as Query or Scan. These operations let you provide your own conditions for selection criteria and filtering. DynamoDB will evaluate and return only those items that match your conditions.

To write an item, you use operations such as PutItem, UpdateItem and DeleteItem. Using conditional expressions with these operations, you can control how and under what conditions an item can be modified. You can prevent an update from occurring if the item does not meet some condition beforehand. For example, you can prevent PutItem from overwriting an existing item.

Note

The examples in this sections are based on the ProductCatalog item from Case Study: A ProductCatalog Item.

Condition Expressions

A condition expression represents restrictions to put in place when you read and write items in a table. A condition expression is a free-form string that can contain attribute names, document paths, logical operators, and functions. For a complete list of elements allowed in a condition expression, see Condition Expression Reference.

The following are some examples of condition expressions. Note that some of these expressions use placeholders for attribute names and values. For more information, see Using Placeholders for Attribute Names and Values.

  • To prevent PutItem from overwriting an existing item, use a conditional expression that specifies that the partition key of the item does not exist. Since every item in the table must have a partition key, this will prevent any existing item from being overwritten. For example, if the partition key is named 'town', you could use:

    attribute_not_exists(town)

    When this conditional expression is used with the PutItem, DynamoDB first looks for an item whose primary key matches that of the item to be written. Only if the search returns nothing is there no partition key present in the result. Otherwise, the attribute_not_exists function above fails and the write will be prevented.

  • All of the items that have a RearView picture.

    attribute_exists(Pictures.RearView)

  • Only the items that don't have one-star reviews. The expression attribute name, #pr, is a substitute for ProductReviews.

    attribute_not_exists (#pr.OneStar)

    For more information about the # character, see Expression Attribute Names.

  • Simple scalar comparisons. :p represents a number and :bt represents a string.

    Price <= :p

    BicycleType = :bt

  • Two conditions that must both be true. #P and #PC are placeholders for Price and ProductCategory attribute names. :lo and :hi represent values of type Number, and :cat1 and :cat2 represent values of type String.

    (#P between :lo and :hi) and (#PC in (:cat1, :cat2))

You can use any attribute name in a condition expression, provided that the first character is a-z or A-Z and the remaining characters (if present) are a-z, A-Z, or 0-9. If an attribute name does not meet this requirement, you will need to define an expression attribute name as a placeholder. For more information, see Expression Attribute Names.

Condition Expression Reference

This section covers the fundamental building blocks of condition expressions in DynamoDB.

Note

The syntax for ConditionExpression is identical to that of the FilterExpression parameter. FilterExpression is used for querying and scanning data; for more information, see Filtering the Results from a Query or a Scan.

Syntax for Condition Expressions

In the following syntax summary, an operand can be the following:

  • A top-level attribute name, such as Id, Title, Description or ProductCategory

  • A document path that references a nested attribute


condition-expression ::=
      operand comparator operand
    | operand BETWEEN operand AND operand
    | operand IN ( operand (',' operand (, ...) ))
    | function 
    | condition AND condition 
    | condition OR condition
    | NOT condition 
    | ( condition )

comparator ::=
    = 
    | <> 
    | < 
    | <= 
    | > 
    | >=

function ::=
    attribute_exists (path) 
    | attribute_not_exists (path) 
    | attribute_type (path, type) 
    | begins_with (path, substr) 
    | contains (path, operand)
    | size (path)

Making Comparisons

Use these comparators to compare an operand against a range of values, or an enumerated list of values:

  • a = b — true if a is equal to b

  • a <> b — true if a is not equal to b

  • a < b — true if a is less than b

  • a <= b — true if a is less than or equal to b

  • a > b — true if a is greater than b

  • a >= b — true if a is greater than or equal to b

Use the BETWEEN and IN keywords to compare an operand against a range of values, or an enumerated list of values:

  • a BETWEEN b AND c - true if a is greater than or equal to b, and less than or equal to c.

  • a IN (b, c, d) — true if a is equal to any value in the list — for example, any of b, c or d. The list can contain up to 100 values, separated by commas.

Functions

Use the following functions to determine whether an attribute exists in an item, or to evaluate the value of an attribute. These function names are case-sensitive. For a nested attribute, you must provide its full path; for more information, see Document Paths.

FunctionDescription

attribute_exists (path)

True if the item contains the attribute specified by path.

Example: Check whether an item in the Product table has a side view picture.

  • attribute_exists (Pictures.SideView)

attribute_not_exists (path)

True if the attribute specified by path does not exist in the item.

Example: Check whether an item has a Manufacturer attribute

  • attribute_not_exists (Manufacturer)

attribute_type (path, type)

True if the attribute at the specified path is of a particular data type. The type parameter must be one of the following:

  • S — String

  • SS — String Set

  • N — Number

  • NS — Number Set

  • B — Binary

  • BS — Binary Set

  • BOOL — Boolean

  • NULL — Null

  • L — List

  • M — Map

You must use an expression attribute value for the type parameter.

Example: Check whether the QuantityOnHand attribute is of type List. In this example, :v_sub is a placeholder for the string L.

  • attribute_type (ProductReviews.FiveStar, :v_sub)

You must use an expression attribute value for the second parameter.

begins_with (path, substr)

True if the attribute specified by path begins with a particular substring.

Example: Check whether the first few characters of the front view picture URL are http://.

  • begins_with (Pictures.FrontView, :v_sub)

The expression attribute value :v_sub is a placeholder for http://.

contains (path, operand)

True if the attribute specified by path is:

  • a String that contains a particular substring.

  • a Set that contains a particular element within the set.

In either case, operand must be a String.

The path and the operand must be distinct; that is, contains (a, a) will return an error.

Example: Check whether the Brand attribute contains the substring Company.

  • contains (Brand, :v_sub)

The expression attribute value :v_sub is a placeholder for Company.

Example: Check whether the product is available in red.

  • contains (Color, :v_sub)

The expression attribute value :v_sub is a placeholder for Red.

size (path)

Returns a number representing an attribute's size. The following are valid data types for use with size.

If the attribute is of type String, size returns the length of the string.

Example: Check whether the string Brand is less than or equal to 20 characters. The expression attribute value :v_sub is a placeholder for 20.

  • size (Brand) <= :v_sub

If the attribute is of type Binary, size returns the number of bytes in the attribute value.

Example: Suppose that the ProductCatalog item has a Binary attribute named VideoClip, which contains a short video of the product in use. The following expression checks whether VideoClip exceeds 64,000 bytes. The expression attribute value :v_sub is a placeholder for 64000.

  • size(VideoClip) > :v_sub

If the attribute is a Set data type, size returns the number of elements in the set.

Example: Check whether the product is available in more than one color. The expression attribute value :v_sub is a placeholder for 1.

  • size (Color) < :v_sub

If the attribute is of type List or Map, size returns the number of child elements.

Example: Check whether the number of OneStar reviews has exceeded a certain threshold. The expression attribute value :v_sub is a placeholder for 3.

  • size(ProductReviews.OneStar) > :v_sub

Logical Evaluations

Use the AND, OR and NOT keywords to perform logical evaluations. In the list following, a and b represent conditions to be evaluated.

  • a AND b — true if a and b are both true.

  • a OR b — true if either a or b (or both) are true.

  • NOT a — true if a is false; false if a is true.

Parentheses

Use parentheses to change the precedence of a logical evaluation. For example, suppose that conditions a and b are true, and that condition c is false. The following expression evaluates to true:

  • a OR b AND c

However, if you enclose a condition in parentheses, it is evaluated first. For example, the following evaluates to false:

  • (a OR b) AND c

Note

You can nest parentheses in an expression. The innermost ones are evaluated first.

Precedence in Conditions

DynamoDB evaluates conditions from left to right using the following precedence rules:

  • = <> < <= > >=

  • IN

  • BETWEEN

  • attribute_exists attribute_not_exists begins_with contains

  • Parentheses

  • NOT

  • AND

  • OR