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

Step 7: Modify Items in the Table

You can modify an item in a table using UpdateItem or you can delete an item using the DeleteItem operations. You can update item by updating values of existing attributes, add new attributes, or remove existing attributes. You can use keywords in the UpdateItem operation such as Set and Remove to request specific updates.

Step 7.1: Update an Item

The UpdateItem API operation lets you do the following:

  • Add more attributes to an item.

  • Modify the values of one or more attributes in the item.

  • Remove attributes from the item.

To specify which operations to perform, you use an update expression. An update expression is a string containing attribute names, operation keywords (such as SET and REMOVE), and new attribute values. You can combine multiple updates in a single update expression.

For more information, see Reserved Words in the Amazon DynamoDB Developer Guide.

By default, UpdateItem operation does not return any data (empty response). You can optionally specify the ReturnValues parameter to request attribute values as they appeared before or after the update:

  • ALL_OLD returns all attribute values as they appeared before the update.

  • UPDATED_OLD returns only the updated attributes as they appeared before the update.

  • ALL_NEW returns all attribute values as they appear after the update.

  • UPDATED_NEW returns only the updated attributes as they appeared after the update.

In this example, you perform a couple of updates to an item in the Music table.

  1. The following example updates a Music table item by adding a new RecordLabel attribute using the UpdateExpression parameter.

    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"
        },
        UpdateExpression: "SET RecordLabel = :label",
        ExpressionAttributeValues: { 
            ":label": "Global Records"
        },
        ReturnValues: "ALL_NEW"
    };
    
    docClient.update(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. Verify that the item in the response has a RecordLabel attribute.

  3. We now apply multiple changes to the item using the UpdateExpression parameter: Change the price, and remove one of the composers.

    Modify the params object so that it looks like this:

    
    var params = {
        TableName: "Music",
        Key: {
            "Artist":"No One You Know",
            "SongTitle":"Call Me Today"
        },
        UpdateExpression: 
            "SET Price = :price REMOVE Tags.Composers[2]",
        ExpressionAttributeValues: { 
            ":price": 0.89
        },
        ReturnValues: "ALL_NEW"
    };
    
  4. Click the play button arrow to run the code. Verify that the UpdateExpression worked.

Specify a Conditional Write

By default updates are performed unconditionally. You can specify a condition in the UpdateItem operation to perform conditional update. For example, you may want to check if an attribute exists before changing its value, or check the existing value and apply an update only if the existing value meets certain criteria.

The UpdateItem operation provides ConditionExpression parameter for you to specify one or more conditions.

In this example, you add an attribute only if it doesn't already exist.

  1. Modify the params object from Step 7.1: Update an Item so that it looks like this:

    
    var params = {
        TableName: "Music",
        Key: {
            "Artist":"No One You Know",
            "SongTitle":"Call Me Today"
        },
        UpdateExpression: "SET RecordLabel = :label",
        ExpressionAttributeValues: { 
            ":label": "New Wave Recordings, Inc."
        },
        ConditionExpression: "attribute_not_exists(RecordLabel)",
        ReturnValues: "ALL_NEW"
    };
    

  2. Click the play button arrow to run the code. This should fail with response: The conditional request failed because the item already has the RecordLabel attribute.

Specify an Atomic Counter

DynamoDB supports atomic counters, where you use the UpdateItem operation to increment or decrement the value of an existing attribute without interfering with other write requests. (All write requests are applied in the order in which they were received.) For example, a music player application might want to maintain a counter each time song is played. In this case, the application would need to increment this counter regardless of its current value. For more information, go to Atomic Counters in the Amazon DynamoDB Developer Guide.

In this example, we first use the UpdateItem operation to add an attribute (Plays) to keep track of the number of times the song is played. Then, using another UpdateItem operation, we increment its value by 1.

  1. Modify the params object from Step 7.1: Update an Item so that it looks like this:

    
    var params = {
        TableName: "Music",
        Key: {
            "Artist":"No One You Know",
            "SongTitle":"Call Me Today"
        },
        UpdateExpression: "SET Plays = :val",
        ExpressionAttributeValues: { 
            ":val": 0
        },
        ReturnValues: "UPDATED_NEW"
    };
    

  2. Click the play button arrow to run the code. The Plays attribute is added, and its value (zero) is shown in the response.

  3. Now modify the params object so that it looks like this:

    
    var params = {
        TableName: "Music",
        Key: {
            "Artist":"No One You Know",
            "SongTitle":"Call Me Today"
        },
        UpdateExpression: "SET Plays = Plays + :incr",
        ExpressionAttributeValues: { 
            ":incr": 1
        },
        ReturnValues: "UPDATED_NEW"
    };
    

  4. Click the play button arrow to run the code. The Plays attribute is incremented by one.

  5. Run the code a few more times. Each time you do this, Plays is incremented.

Step 7.2: Delete an Item

You now use the DeleteItem API operation to delete an item from the table. Note that this operation is permanent—there is no way to restore an item.

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

    
    var params = {
        TableName: "Music",
        Key: {
            Artist: "The Acme Band", 
            SongTitle: "Look Out, World"
        }
    };
    
    docClient.delete(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 item is deleted.

Specify a Conditional Delete

By default, a delete operation is unconditional. However, you can use the ConditionExpression parameter to perform conditional deletes. In this example you delete an item, only if its price is 0.

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

    
    var params = {
        TableName: "Music",
        Key: {
            Artist: "No One You Know", 
            SongTitle: "My Dog Spot"
        },
        ConditionExpression: "Price = :price",
        ExpressionAttributeValues: {
            ":price": 0.00
        }
    };
    
  2. Click the play button arrow to run the code. The conditional delete fails because the song is not free (Price is not 0.00).

Next Step

Step 8: Clean Up