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

Using Placeholders for Attribute Names and Values

This section introduces placeholders, or substitution variables, that you can use in DynamoDB expressions.

Expression Attribute Names

On some occasions, you might need to write an expression containing an attribute name that conflicts with a DynamoDB reserved word. (For a complete list of reserved words, see Reserved Words in DynamoDB.)

For example, the following projection expression would be invalid because SESSION is a reserved word:

  • Classroom, Session, StartTime

To work around this, you can define an expression attribute name. An expression attribute name is a placeholder that you use in the expression, as an alternative to the actual attribute name. An expression attribute name must begin with a #, and be followed by one or more alphanumeric characters.

In the preceding expression, you can replace Session with an expression attribute name such as #s. The # (pound sign) is required and indicates that this is a placeholder for an attribute name. The revised expression would now look like this:

  • Classroom, #s, StartTime

Tip

If an attribute name begins with a number or contains a space, a special character, or a reserved word, then you must use an expression attribute name to replace that attribute's name in the expression.

In an expression, a dot (".") is interpreted as a separator character in a document path. However, DynamoDB also allows you to use a dot character as part of an attribute name. This can be ambiguous in some cases. To illustrate, consider the following item in a DynamoDB table:


{
    Id: 1234,
    My.Scalar.Message: "Hello",
    MyMap: {
        MyKey: "My key value",
        MyOtherKey: 10
    }
}

Suppose that you wanted to access My.Scalar.Message using the following projection expression:

My.Scalar.Message

DynamoDB would return an empty result, rather than the expected Hello string. This is because DynamoDB interprets a dot in an expression as a document path separator. In this case, you would need to define an expression attribute name (such as #msm) as a substitute for My.Scalar.Message. You could then use the following projection expression:

#msm

DynamoDB would then return the desired result: Hello

Tip

A dot in an expression represents a document path separator.

If an attribute name contains dot characters, define an expression attribute name for it. You can then use that name in an expression.

Now suppose that you wanted to access the embedded attribute MyMap.MyKey, using the following projection expression:

MyMap.MyKey

The result would be My key value, which is expected.

But what if you decided to use an expression attribute name instead? For example, what would happen if you were to define #mmmk as a substitute for MyMap.MyKey? DynamoDB would return an empty result, instead of the expected string. This is because DynamoDB interprets a dot in an expression attribute value as a character within an attribute's name. When DynamoDB evaluates the expression attribute name #mmmk, it determines that MyMap.MyKey refers to a scalar attribute—which is not what was intended.

The correct approach would be to define two expression attribute names, one for each element in the document path:

  • #mm — MyMap

  • #mk — MyKey

You could then use the following projection expression:

#mm.#mk

DynamoDB would then return the desired result: My key value

Note

A dot in an expression attribute name represents a valid character within an attribute's name.

To access a nested attribute, define an expression attribute name for each element in the document path. You can then use these names in an expression, with each name separated by a dot.

Expression attribute names are also helpful when you need to refer to the same attribute name repeatedly. For example, consider the following expression for retrieving some of the reviews from a ProductCatalog item:

  • ProductReviews.FiveStar, ProductReviews.ThreeStar, ProductReviews.OneStar

To make this more concise, you can replace ProductReviews with an expression attribute name such as #pr. The revised expression would now look like this:

  • #pr.FiveStar, #pr.ThreeStar, #pr.OneStar

If you define an expression attribute name, you must use it consistently throughout the entire expression. Also, you cannot omit the # symbol.

Note

The way you specify expression attribute names depends on the programming language that you use. For code samples, see the Amazon DynamoDB Getting Started Guide section for your language.

Expression Attribute Values

If you need to compare an attribute with a value, define an expression attribute value as a placeholder. Expression attribute values are substitutes for the actual values that you want to compare — values that you might not know until runtime. An expression attribute value must begin with a :, and be followed by one or more alphanumeric characters

For example, suppose you have an application that shows products costing less than a certain value, with the actual value to be entered by the user. You can define an expression attribute value, such as :p, as a placeholder. The : is required, and indicates that this is a placeholder for an attribute value. Such an expression would look like this:

  • Price < :p

At runtime, the application can prompt the user for the desired price. This price will be used in the expression, and DynamoDB will retrieve the desired results.

If you define an expression attribute value, you must use it consistently throughout the entire expression. Also, you cannot omit the : symbol.

Note

The way you specify expression attribute values depends on the programming language that you use. For code samples, see the Amazon DynamoDB Getting Started Guide section for your language.