DynamoDB PutItem vs UpdateItem - Understand The Difference

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

The updateItem 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:

var params = { 
  ExpressionAttributeNames: { 
    "#T": "Topic", 
    "#D": "Date" 
  }, 
  ExpressionAttributeValues: { 
    ":t": { 
      S: "DynamoDB" 
    }, 
    ":d": { 
      N: "2022" 
    } 
  }, 
  Key: { 
    "ArticleId": { 
      S: "A001" 
    }}, 
  ReturnValues: "ALL_NEW", 
  TableName: "Article", 
  UpdateExpression: "SET #D = :d, #T = :t" 
};

dynamodb.updateItem(params, function(err, data) { 
   if (err) console.log(err, err.stack); 
   else console.log(data); 
});
var params = { 
  ExpressionAttributeNames: { 
    "#T": "Topic", 
    "#D": "Date" 
  }, 
  ExpressionAttributeValues: { 
    ":t": { 
      S: "DynamoDB" 
    }, 
    ":d": { 
      N: "2022" 
    } 
  }, 
  Key: { 
    "ArticleId": { 
      S: "A001" 
    }}, 
  ReturnValues: "ALL_NEW", 
  TableName: "Article", 
  UpdateExpression: "SET #D = :d, #T = :t" 
};

dynamodb.updateItem(params, function(err, data) { 
   if (err) console.log(err, err.stack); 
   else console.log(data); 
});

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 Topic 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: { 
     "Topic": { S: "DynamoDB" }, 
     "Date": { N: "2022" }, 
  } ,
  ConsumedCapacity: { 
    CapacityUnits: 1, 
    TableName: "Article" 
  } ,
  ItemCollectionMetrics: { 
    ItemCollectionKey: { ... },
    SizeEstimateRangeGB: [2, 3]
  }
}
{ 
   Attributes: { 
     "Topic": { S: "DynamoDB" }, 
     "Date": { N: "2022" }, 
  } ,
  ConsumedCapacity: { 
    CapacityUnits: 1, 
    TableName: "Article" 
  } ,
  ItemCollectionMetrics: { 
    ItemCollectionKey: { ... },
    SizeEstimateRangeGB: [2, 3]
  }
}

• Attributes - Attribute values as defined using the ReturnValues 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 in a DynamoDB table. So, unlike the updateItem function, you cannot use the putItem function to update existing items partially.

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.

var params = { 
  Item: { 
    "Topic": { 
      S: "DynamoDB" 
    }, 
    "Writer": { 
      S: "Chameera" 
    }, 
    "Date": { 
      S: "2022" 
    } 
  }, 
  ReturnConsumedCapacity: "TOTAL", 
  TableName: "Article" 
};
 
dynamodb.putItem(params, function(err, data) { 
   if (err) console.log(err, err.stack); 
   else console.log(data); 
});
var params = { 
  Item: { 
    "Topic": { 
      S: "DynamoDB" 
    }, 
    "Writer": { 
      S: "Chameera" 
    }, 
    "Date": { 
      S: "2022" 
    } 
  }, 
  ReturnConsumedCapacity: "TOTAL", 
  TableName: "Article" 
};
 
dynamodb.putItem(params, function(err, data) { 
   if (err) console.log(err, err.stack); 
   else console.log(data); 
});

In addition to the only required parameter, the 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: { 
     "Topic": { S: "DynamoDB" }, 
     "Date": { S: "2022" }, 
  } ,
  ConsumedCapacity: { 
    CapacityUnits: 1, 
    TableName: "Article" 
  } ,
  ItemCollectionMetrics: { 
    ItemCollectionKey: { ... },
    SizeEstimateRangeGB: [2, 3]
  }
}
{ 
   Attributes: { 
     "Topic": { S: "DynamoDB" }, 
     "Date": { S: "2022" }, 
  } ,
  ConsumedCapacity: { 
    CapacityUnits: 1, 
    TableName: "Article" 
  } ,
  ItemCollectionMetrics: { 
    ItemCollectionKey: { ... },
    SizeEstimateRangeGB: [2, 3]
  }
}

• Attributes - Attribute values as defined using the ReturnValues 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.

Use Cases and Best Practices

Understanding when to use putItem versus updateItem can significantly impact the efficiency and cost-effectiveness of your DynamoDB operations. For instance, if you need to update only a few attributes of an item, using updateItem is more efficient as it avoids the need to rewrite the entire item. On the other hand, if you need to replace an entire item or ensure that an item is created if it does not exist, putItem is the appropriate choice.

Additionally, using conditional expressions with both putItem and updateItem can help maintain data integrity by ensuring that updates or inserts only occur when certain conditions are met. This is particularly useful in scenarios where multiple clients might be accessing and modifying the same data concurrently.

Finally, always monitor the ConsumedCapacity and ItemCollectionMetrics to understand the impact of your operations on your provisioned throughput and to optimize your table's performance. Properly managing these metrics can help you avoid throttling and ensure that your application runs smoothly.

By understanding these nuances and best practices, you can make more informed decisions and optimize your use of DynamoDB for your specific needs.