dynobase-icon
Dynobase

DynamoDB PutItem vs UpdateItem - Understand The Difference

Chameera Dulanga

Written by Chameera Dulanga

Published on August 14th, 2022

    Still using AWS console to work with DynamoDB? 🙈

    Time to 10x your DynamoDB productivity with Dynobase [learn more]

    Two of the most used write methods in DynamoDB are updateItem and putItem. Although both these functions sound like they serve the same purpose, there are some significant fundamental differences between them.

    This article will discuss how and when to use updateItem and putItem functions in DynamoDB and the difference between them to better understand you.

    DynamoDB UpdateItem

    TheupdateItem function is used to update an existing item's attributes. Overall, developers can add, edit, or delete attributes from an existing item using the updateItem function.

    In addition, it allows developers to perform conditional updates, and they can return the updated attribute values in the same query using the ReturnValues parameter.

    For example, if you are using DynamoDB JavaScript SDK, you need to create a request object with necessary parameters and pass it to the updateItem function:

    The above example will update the item within the Article table. The primary key of the updated item is A001, and it will add a new attribute named Date and modify the Title attribute. Also, it will return all the attribute values after the update since the ReturnValues parameter is set to ALL_NEW.

    Apart from that, there are many other parameters that you can use in the request object of the updateItem function. The below list will give a brief introduction to those parameters.

    DynamoDB UpdateItem - Request Parameters

    • Key - Primary key of the table. You must provide all the attributes if the primary key is composite.
    • TableName - Name of the DynamoDB table.
    • ConditionExpression - Condition of the conditional update.
    • ExpressionAttributeNames - Substitution tokens for attribute names in an expression.
    • ExpressionAttributeValues - Values that can be substituted in an expression.
    • ReturnConsumedCapacity - The level of detail on provisioned or on-demand throughput consumption.
    • ReturnItemCollectionMetrics - Determines whether item collection metrics are returned.
    • ReturnValues - To return item attributes in the response using the same operation.
    • UpdateExpression - Used to define attributes to be updated.

    Read more about request parameters here.

    DynamoDB UpdateItem - Response Elements

    A successful updateItem operation will return a response object with 3 elements:

    • Attributes - Attribute values as defined using the ReturnValue parameter.
    • ConsumedCapacity - The number of capacity units consumed by the operation.
    • ItemCollectionMetrics - Details of the collections affected by the update operation. You need to specify the ReturnItemCollectionMetrics parameter in the request object to retrieve this.

    Read more about response elements here.

    DynamoDB PutItem

    The putItem function creates an entirely new item or replaces an existing item from a DynamoDB table. So, unlike the updateItem function, you can not use the putItem function to update existing items.

    The behavior of the putItem function is determined by the primary key you provide. For example, if you provide an existing primary key, it will completely replace the old item.

    The only required parameter in the request object is the primary key. The below example shows how to use the putItem function to add a new item into a DynamoDb table using the DynamoDB JavaScript SDK.

    In addition to the only required parameter, putItem function supports many other parameters in the request object. The below list will briefly introduce those parameters.

    DynamoDB PutItem - Request Parameters

    • Item - Includes attribute names and values.
    • TableName - Name of the DynamoDB table.
    • ConditionExpression - Condition of the conditional update.
    • ExpressionAttributeNames - Substitution tokens for attribute names in an expression.
    • ExpressionAttributeValues - Values that can be substituted in an expression.
    • ReturnConsumedCapacity - The level of detail on provisioned or on-demand throughput consumption.
    • ReturnItemCollectionMetrics - Determines whether item collection metrics are returned.
    • ReturnValues - To return item attributes in the response using the same operation.

    Read more about request parameters here.

    DynamoDB PutItem - Response Elements

    Similar to updateItem, a successful putItem operation will return a response object with 3 elements:

    • Attributes - Attribute values as defined using the ReturnValue parameter.
    • ConsumedCapacity - The number of capacity units consumed by the operation.
    • ItemCollectionMetrics - Details of the collections affected by the update operation. You need to specify the ReturnItemCollectionMetrics parameter in the request object to retrieve this.

    Read more about response elements here.

    Main Difference Between DynamoDB UpdateItem & PutItem

    I think now you have a good understanding of how putItem and updateItem functions work and when we need to use them. As discussed above, both these functions have a large set of similar parameters in request and response objects.

    However, the primary purpose of putItem and updateItem functions are completely different. The putItem function is used to replace an existing item or to create a new item. In contrast, the updateItem function is used to add, edit or delete attributes from an existing item.

    Some might argue that the above claim is incorrect since there is a way you can use the putItem function to update the attributes of an item. But, if you use the putItem function for updates, you must pass all the attribute values to the function to ensure that you do not replace anything. This can be exhausting when the number of attributes in the table is high.

    So, it is always good to use the updateItem function to update item attributes and the putItem function to create or replace new items.

    Better DynamoDB experience.

    Start your 7-day free trial today

    Product Features

    © 2022 Dynobase