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

Accessing Item Attributes with Projection Expressions

To read data from a table, you use operations such as GetItem, Query or Scan. DynamoDB returns all of the item attributes by default. To get just some of the attributes, rather than all of them, use a projection expression.

Note

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

Projection Expressions

A projection expression is a string that identifies the attributes you want. To retrieve a single attribute, specify its name. For multiple attributes, the names must be comma-separated.

The following are some examples of projection expressions:

  • A single top-level attribute.

    Title

  • Three top-level attributes. Note that DynamoDB will retrieve the entire Color set.

    Title, Price, Color

  • Four top-level attributes. Note that DynamoDB will return the entire contents of RelatedItems and ProductReviews.

    Title, Description, RelatedItems, ProductReviews

You can use any attribute name in a projection expression, provided that the first character is a-z or A-Z and the second character (if present) is 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.

Document Paths

In addition to top-level attributes, expressions can access individual elements in any document type attribute. To do this, you must provide the element's location, or document path, within the item. The document path tells DynamoDB where to find the attribute, even if it is deeply nested within multiple lists and maps.

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.

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:

  • MyList[0]

  • AnotherList[12]

  • ThisList[5][11]

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

The index in a list dereference must be a non-negative integer. Therefore, the following expressions are invalid:

  • MyList[-1]

  • MyList[0.4]

Accessing Map Elements

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

  • MyMap.nestedField

  • MyMap.nestedField.deeplyNestedField

Document Path Examples

The following are some examples of projection expressions using document paths.

  • The third element from the RelatedItems list. (Remember that list elements are zero-based.)

    RelatedItems[2]

  • The item's price, color, and a front-view picture of the product.

    Price, Color, Pictures.FrontView

  • All of the five-star reviews.

    ProductReviews.FiveStar

  • The first of the five-star reviews.

    ProductReviews.FiveStar[0]

Note

The maximum depth for a document path is 32. Therefore, the number of dereferences in any path cannot exceed this limit.

You can use any attribute name in a document path, provided that the first character is a-z or A-Z and the second character (if present) is 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.