Inserting and replacing items with put in the DynamoDB node.js DocumentClient
Put is responsible for both inserting new items and also completely overwriting items. We cover capacity units and how they are affected by GSIs on a given table, ConditionExpressions for preventing the overwriting of items, as well as how to use ReturnValues
Instructor: [0:00] On the right here, we're using the AWS SDK to set up the Node.js DocumentClient for DynamoDB. On the top is all of our setup for the client. Here we have a set of params that we're going to be modifying as we make various put requests. At the bottom, we have some machinery that runs our put request when we run our script.
[0:17] On the left, we have an empty DynamoDB table. Our first request, we'll insert one item with a PK of user #5 and SK of user #5 and a text attribute of testing. We also have two additional keys, ReturnValues and ReturnConsumedCapacity that we'll go over shortly.
[0:35] After running the script and refreshing the DynamoDB console, we can see that we have an item with a PK of user 5 and SK of todo 5 and a text attribute with testing. On the right, we can see that we've used two capacity units on the testing table.
[0:49] The capacity units that we've consumed are returned because we've specified that ReturnConsumedCapacity should give us the total capacity.
[0:56] Notice that we've specified return values to all old, which is why we don't have any data here because this was the first time we've put this object into the table. If we run the exact same script again, we can see that nothing has changed in the table, but we've gotten back a set of attributes.
[1:10] Our capacity units have dropped to one 1 of 2. This is because of DynamoDB put request. If it matches for the primary key for the item, we'll do a complete replacement of that item in the table.
[1:21] For example, if we keep the PK and the SK the same, which identify the item and we enable this new attribute called data with the value of replace true and we remove the text attribute and rerun the script, we can see that our capacity units bump back up to 2.
[1:34] We can see that the old attributes included the text attribute. In the DynamoDB console, we can see that our item with a user of 5 and a todo of 5 now has a data attribute but doesn't have a text attribute.
[1:45] This proves that if we match on the PK and the SK or the primary key, we're doing a full replace of our item in the table. This is the difference between put and update, which we cover in another video.
[1:56] To get some more insight into what's going on with our capacity usage, we can use indexes instead of total for the ReturnConsumedCapacity value. If we change our item to be a completely new item with a user 6 and a todo 6 and we run our script, we can now see the capacity units in an expanded manner.
[2:12] The ConsumedCapacity, which is the only root key that we get back because we've inserted a new object and don't have any old values.
[2:18] We've used two capacity units total. One of which was used on the table itself and one of which was used on the SK index, which is a GSI that we set up. This is because indexes are basically copies of our data. If we have an index that matches, the insert happens not only on the table, but also on the index.
[2:34] If we refresh the DynamoDB console, we can see that we have user 6, todo 6 with the data. If we run the exact same script again, we can see that the change was not replicated to the index because none of the data actually changed. Our ConsumedCapacity is only one unit.
[2:49] Because a put request overwrites the entire item, it can be useful to use condition expressions to restrict whether or not we actually do that if an item already exists in the table. In this case, I just rerun the query, replacing the data attribute with text. I'm also going to delete todo #5 to make this a little easier for us to see.
[3:08] Now we have a single todo with a PK of user 6, a todo of 6 and a text attribute that says testing. Let's say in this case that we want to insert this item, but only if the text attribute doesn't already exist. We can use a condition expression to check for the existence of the text attribute.
[3:24] Note the text is a reserved word in DynamoDB. We have to use expression attribute names to replace it in this condition expression. Now, this query will only succeed if the text attribute does not exist. Note that we've changed the text to confirm this.
[3:36] When we run this query, we can see that our conditional check has failed because user 6, todo 6 already has a text attribute. Note that we don't get much other information other than the fact that the conditional check failed. We can choose to reverse this check and check to see if the attribute exists and run our script again.
[3:53] Note that this time, we were successful. After refreshing the page in the DynamoDB console, we can see that the new text was inserted.
[4:00] If you look at the DynamoDB docs for put, you can see two of the expressions that we just used, attribute_exists and attribute_not_exists. There's also attribute_type, contains, begins_with and size. The function names are case sensitive, so you can't make these capitalized like you might in SQL.
[4:16] There are a number of comparison operators and you can also combine these statements with and, or, or not. You can use these condition expressions to guard against unwanted changes to the data.