DynamoDB Node.js Query Examples
This cheat sheet should help you how to perform basic query operations with DynamoDB and Node.JS
There are two basic ways to interact with DynamoDB tables from Node.js applications:
AWS.DynamoDB.DocumentClientwhich simplifies working with DynamoDB items by abstracting away DynamoDB Types and converting responses to native JS
This cheat sheet will mostly focus on
DocumentClient but some of the operations like creating tables must be run using classical DynamoDB service.
If you're looking for similar cheat sheet but for Python, you can find it here
Table of Contents
- Setting up
- Create Table
- Get All Items / Scan
- Get Item
- Batch Get Item
- Put Item
- Query Set of Items
- Update Item
- Conditionally Update Item
- Increment Item Attribute
- Delete Item
- Delete All Items
- Query with Sorting
- Query Pagination
- Run DynamoDB Local
Setting up your Node.js application to work with DynamoDB is fairly easy. First, make sure that
aws-sdk is installed, either by running
yarn add aws-sdk or
npm i aws-sdk --save. Then, paste following piece of code:
As one of the Node.js best practices is to avoid callback hell, we'll be ending up all of our SDK calls with
.promise() call in order to get Promises returned from SDK. It will also allow us to use
async/await syntax which makes our programs much more readable.
Keep in mind that using access and secret keys is against best security practices, and you should instead use IAM roles/policies to interact with DynamoDB. This code, if ran on Lamba function or EC2 instance, will automatically use IAM Role attached to it.
After this call resolves, it does not necessarily mean that table status is
ACTIVE and it's is ready for read and write operations. Before start manipulating items in it, we should check if it's in
ACTIVE state first:
After our table is provisioned and it's in
ACTIVE state, first thing that we probably would like to do is get all items in it aka use (DynamoDB Scan operation):
If you want to narrow your search results, use
FilterExpressions combined with
ExpressionAttributeNames object like so:
You can find full reference how to write
FilterExpressions in this post by Alex Debrie
If you know the exact Partition Key (and Sort Key if using composite key) of the item that you want to retrieve from the DynamoDB table, you can use
DocumentClient is also capable of running bunch of
get operations in a single call to the DynamoDB service:
As you can see, the
RequestItems objects can accept multiple table names and can fetch multiple items from multiple tables in a single call. Keep in mind that number of items retrieved using
batchGet is limited to 100 items or 16MB of data.
Moreover, if you exceed table capacity, this call will return
UnprocessedKeys attribute containing a map of keys which weren't fetched.
put operation creates a new item, or replaces an old item with a new item if it's using the same key(s):
If your table has composite key (which is the best practice), in order to get a collection of items sharing the same Parition Key, use
Query method. It also allows to use multiple operators for SortKey such as
begins_with or mathematical ones like
>= and so on.
Keep in mind that
Query can return up to 1MB of data and you can also use
FilterExpressions here to narrow the results on non-key attributes.
Unfortunately, DynamoDB offers only one way of sorting the results on the database side - using the sort key. If your table does not have one, your sorting capabilities are limited to sorting items in application code after fetching the results. However, if you need to sort DynamoDB results on sort key descending or ascending, you can use following syntax:
Both Query and Scan operations returns results up to 1MB of items. If you need to fetch more records, you need to invoke a second call to fetch the next page of results. If
LastEvaluatedKey is present in response object, this table has more items like requested and another call with
ExclusiveStartKey should be sent to fetch more of them:
update operation in Node.js consists of two main parts:
- Part which item to update (
Key), similar to get
- Part what in the selected item should be updated (
Sometimes we want to update our record only if some condition is met, e.g. item is not soft-deleted (does not have
deletedAt attribute set). To do that, use
ConditionExpression which has similar syntax to the
In this example the
name attribute of the record with partition key
id = 123 in table
my-table will be only updated if this item does not have attribute
deletedAt and its attribute
company has value
Incrementing a Number value in DynamoDB item can be achieved in two ways:
- Get item, update the value in the application code and send a
putrequest back to DDB overwriting item
While it might be tempting to use first method because Update syntax is unfriendly, I strongly recommend using second one because of the fact it's much faster (requires only one request) and atomic:
In this example the
score attribute of the record with partition key
id = 123 in table
my-table will incremented by one.
Removing single item from table is very similar to Get Item operation. The parameters of the call are actually exactly the same, the only difference is that we call
delete instead of
Unfortunately, there's no easy way to delete all items from DynamoDB just like in SQL-based databases by using
DELETE FROM my-table;. To achieve the same result in DynamoDB, you need to query/scan to get all the items in a table using pagination until all items are scanned and then perform
delete operation one-by-one on each record.
Luckily, truncating table is possible just with few clicks using Dynobase.
If you need to use DynamoDB offline locally, you can use DynamoDB local distributed by AWS or DynamoDB from Localstack. Connecting to it is as easy as changing the
If you want to see your local tables and data in them, you can use Dynobase to query and modify items in offline tables.
© 2020 Dynobase