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

Step 4: Read an Item Using Its Primary Key

DynamoDB provides the GetItem operation for retrieving one item at a time. You can retrieve an entire item, or a subset of its attributes.

DynamoDB supports the Map and List attribute types. These attribute types allow you to nest other attributes within them, so that you can store complex documents in an item. You can use GetItem to retrieve an entire document, or just some of the nested attributes within that document.

Step 4.1: Read an Item Using GetItem

Use the GetItem API operation to read an item. You must provide the primary key of the item you want. DynamoDB then reads the item directly from its physical location in the database.

The following code reads an item from the Music table by specifying the primary key.

  1. Replace everything in the left side of the DynamoDB JavaScript shell window with the following code:

    
    var params = { 
        TableName: "Music",
        Key: {
            "Artist": "No One You Know",
            "SongTitle": "Call Me Today"
        }
    };
    
    docClient.get(params, function(err, data) {
        if (err)
            console.log(JSON.stringify(err, null, 2));
        else
            console.log(JSON.stringify(data, null, 2));
    });
    
    
  2. Click the play button arrow to run the code. The requested item appears in the response.

  3. (Optional) You can change the primary key in the preceding code to retrieve different music items. Let us retrieve different music items from the table.

    Modify the params object, using any of the primary key values shown below. Click the play button arrow to run the code, and verify that the correct item is returned in the response.

    
        Key: {
            "Artist": "No One You Know",
            "SongTitle": "My Dog Spot"
        }
    
    
        Key: {
            "Artist": "No One You Know",
            "SongTitle": "Somewhere Down The Road"
        }
    
    
        Key: {
            "Artist": "The Acme Band",
            "SongTitle": "Still In Love"
        }
    
    
        Key: {
            "Artist": "The Acme Band",
            "SongTitle": "Look Out, World"
        }
    

Step 4.2: Retrieve a Subset of Attributes Using a Projection Expression

By default, the GetItem API operation returns all of the attributes in the item. To return only some of the attributes, you provide a projection expression — a comma-separated string of attribute names that you want to use.

  1. In the DynamoDB JavaScript shell window, modify the params object so that it looks like this:

    
    var params = { 
        TableName: "Music",
        Key: {
            "Artist": "No One You Know",
            "SongTitle": "Call Me Today"
        },
        ProjectionExpression: "AlbumTitle"
    };
    
  2. Click the play button arrow to run the code. Only one attribute (AlbumTitle) appears in the response.

Handling Attribute Names that Are Also Reserved Words

In DynamoDB, you have a great deal of flexibility when it comes to naming your tables and attributes. However, it is possible that a name you choose might conflict with a reserved word. In this situation, you can define an expression attribute name and use it in the projection expression.

For the complete list, see Reserved Words in the Amazon DynamoDB Developer Guide.

  1. Modify the projection expression so that it also includes the Year attribute, which is a reserved word and therefore the GetItem operation fails:

    
    var params = { 
        TableName: "Music",
        Key: {
            "Artist": "No One You Know",
            "SongTitle": "Call Me Today"
        },
        ProjectionExpression: "AlbumTitle, Year"
    };
    
  2. Click the play button arrow to run the code. An error message appears in the response:

    Invalid ProjectionExpression: Attribute name is a reserved keyword; reserved keyword: Year

  3. Modify the params object to use a placeholder token (#y) in ProjectionExpression, and then define the placeholder in the ExpressionAttributeNames parameter.

    
    var params = { 
        TableName: "Music",
        Key: {
            "Artist": "No One You Know",
            "SongTitle": "Call Me Today"
        },
        ProjectionExpression: "AlbumTitle, #y",
        ExpressionAttributeNames: {"#y": "Year"}
    };
    

    In the ProjectionExpression, the word Year is replaced by the token #y. The # (pound sign) is required, and indicates that this is a placeholder. The ExpressionAttributeNames parameter indicates that #y is to be replaced by Year at runtime.

  4. Click the play button arrow to run the code. The AlbumTitle and Year attributes appear in the response.

Step 4.3: Retrieve Nested Attributes Using Document Path Notation

DynamoDB supports a map type attribute to store documents. In the Music table, we use a map type attribute called Tags to store information such as list of music composers, song duration information, and so on. These are nested attributes. You can retrieve entire document, or a subset of these nested attributes by specifying document path notation.

A document path tells DynamoDB where to find the attribute, even if it is deeply nested within multiple lists and maps. In a document path, use the following operators to access nested attributes:

  • For a list, use square brackets: [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.

  • For a map, use a dot: . The dot acts as a separator between elements in the map.

  1. Modify the params object so that it looks like this:

    
    var params = { 
        TableName: "Music",
        Key: {
            "Artist": "No One You Know",
            "SongTitle": "Call Me Today"
        },
        ProjectionExpression: "AlbumTitle, #y, Tags.Composers[0], Tags.LengthInSeconds",
        ExpressionAttributeNames: {"#y": "Year"}
    };
    
  2. Click the play button arrow to run the code. The response contains only the top-level and nested attributes that were specified in ProjectionExpression.

Step 4.4: Read Multiple Items Using BatchGetItem

The GetItem operation retrieves a single item by its primary key. DynamoDB also supports BatchGetItem operation for you to read multiple items in a single request. You specify a list of primary keys for this operation.

The following example retrieves a group of music items. The example also specifies the optional ProjectionExpression to retrieve only a subset of the attributes.

  1. Replace everything in the left side of the DynamoDB JavaScript shell window with the following code:

    
    var params = {
        RequestItems: {
            "Music": {
                Keys: [
                    {
                        "Artist": "No One You Know",
                        "SongTitle": "My Dog Spot"
                    },
                    {
                        "Artist": "No One You Know",
                        "SongTitle": "Somewhere Down The Road"
                    },
                    {
                        "Artist": "The Acme Band",
                        "SongTitle": "Still In Love"
                    },
                    {
                        "Artist": "The Acme Band",
                        "SongTitle": "Look Out, World"
                    }
                ],
                ProjectionExpression:"PromotionInfo, CriticRating, Price"
            }
        }
    };
    
    docClient.batchGet(params, function (err, data) {
        if (err)
            console.log(JSON.stringify(err, null, 2));
        else
            console.log(JSON.stringify(data, null, 2));
    });
    
    
  2. Click the play button arrow to run the code. The response contains all of the attributes specified in ProjectionExpression. If one of the items does not have any of the specified attributes, it appears in the response as an empty map: {}

  3. (Optional) Remove the ProjectionExpresion entirely, and retrieve all of the attributes from the items.

  4. (Optional) Add a new ProjectionExpression that retrieves at least one nested attribute. Use document path notation to do this.