Referring to item attributes when using expressions in DynamoDB

This section describes how to refer to item attributes in an expression in Amazon DynamoDB. You can work with any attribute, even if it is deeply nested within multiple lists and maps.

A Sample Item: ProductCatalog

The examples on this page use the following sample item in the ProductCatalog table. (This table is described in Example tables and data for use in DynamoDB.)

{
    "Id": 123,
    "Title": "Bicycle 123",
    "Description": "123 description",
    "BicycleType": "Hybrid",
    "Brand": "Brand-Company C",
    "Price": 500,
    "Color": ["Red", "Black"],
    "ProductCategory": "Bicycle",
    "InStock": true,
    "QuantityOnHand": null,
    "RelatedItems": [
        341,
        472,
        649
    ],
    "Pictures": {
        "FrontView": "http://example.com/products/123_front.jpg",
        "RearView": "http://example.com/products/123_rear.jpg",
        "SideView": "http://example.com/products/123_left_side.jpg"
    },
    "ProductReviews": {
	    "FiveStar": [
	    		"Excellent! Can't recommend it highly enough! Buy it!",
	    		"Do yourself a favor and buy this."
	    ],
	    "OneStar": [
	    		"Terrible product! Do not buy this."
	    ]
    },
    "Comment": "This product sells out quickly during the summer",
    "Safety.Warning": "Always wear a helmet"
 }

Note the following:

Top-level attributes

An attribute is said to be top level if it is not embedded within another attribute. For the ProductCatalog item, the top-level attributes are as follows:

All of these top-level attributes are scalars, except for Color (list), RelatedItems (list), Pictures (map), and ProductReviews (map).

Nested attributes

An attribute is said to be nested if it is embedded within another attribute. To access a nested attribute, you use dereference operators:

Accessing list elements

The dereference operator for a list element is [N], where n is the element number. List elements are zero-based, so [0] represents the first element in the list, [1] represents the second, and so on. Here are some examples:

The element ThisList[5] is itself a nested list. Therefore, ThisList[5][11] refers to the 12th element in that list.

The number within the square brackets must be a non-negative integer. Therefore, the following expressions are not valid:

Accessing map elements

The dereference operator for a map element is . (a dot). Use a dot as a separator between elements in a map:

Document paths

In an expression, you use a document path to tell DynamoDB where to find an attribute. For a top-level attribute, the document path is simply the attribute name. For a nested attribute, you construct the document path using dereference operators.

The following are some examples of document paths. (Refer to the item shown in Referring to item attributes when using expressions in DynamoDB.)

You can use any attribute name in a document path as long as they meet these requirements:

For more information, see Expression attribute names (aliases) in DynamoDB.