August 7, 2023

Getting Started with Dynamoose

The best time to establish protocols with your clients is when you onboard them.


Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse varius enim in eros elementum tristique. Duis cursus, mi quis viverra ornare, eros dolor interdum nulla, ut commodo diam libero vitae erat. Aenean faucibus nibh et justo cursus id rutrum lorem imperdiet. Nunc ut sem vitae risus tristique posuere.


Dynamoose is a Node.js modeling tool built for AWS DynamoDB. It serves as an Object Data Modeling (ODM) library and abstracts away many of the low-level details of interacting with DynamoDB, making it simpler and more convenient to use for developers.

Dynamoose offers key features that make working with DynamoDB easy.

  1. Automatic schema creation: Dynamoose automatically creates a schema for your data based on your defined models. This eliminates the need to manually create and manage the schema in DynamoDB. This uses the Dynamoose model() function to get the parameters, define its datatype and other constraints, and create the schema.
  2. Type validation: Dynamoose ensures type safety by validating the data types of attributes against the defined schema. This helps prevent data type errors and inconsistencies.
  3. Query building: It simplifies the process of building queries for DynamoDB. It provides a query builder API that allows you to construct complex queries easily.
  4. Data transformation: Allows you to transform data before saving or retrieving it from the database. This feature is useful for tasks like data encryption, decryption, or formatting.
  5. Strict data modeling: Enforces strict data modeling by supporting validation rules, required attributes, and other constraints. This helps maintain data integrity and consistency.
  6. Support for DynamoDB Transactions: Dynamoose includes support for DynamoDB transactions, enabling atomic and consistent operations across multiple items or tables.
  7. Conditional and filtering support: Provides powerful support for conditional operations and filtering, allowing you to retrieve only the required data based on specified conditions.
  8. Callback and Promise Support: It offers support for both Callbacks and Promises, allowing you to use either asynchronous programming style based on your preference.
  9. AWS multi-region support: It supports multi-region deployment on Amazon Web Services, enabling you to operate in multiple regions for improved availability and performance.

Setting up Dynamoose

  1. Install the Dynamoose package from npm by running the following command in your terminal — npm install dynamoose
  2. To connect to DynamoDB, you need to set up your AWS credentials. If you haven’t done so already, create an AWS account and generate your access key ID and secret access key. You can then set up your AWS credentials by either:
    a. Setting up .aws/credentials folder and adding your profile there (or)
    b. Configuring your project env variables with an access ID and secret key
  3. Create a DynamoDB table: Before using Dynamoose, you need to have a DynamoDB table to work with. You can create a table manually in the AWS Management Console or use the AWS SDK or AWS CLI to create it programmatically.
  4. Now that Dynamoose is installed, impor tinto your project using

Define the models, let us take ‘user’ model for example:

Here, we create the schema using dynamoose.model() for the ‘User’ model. Let’s dive into the code provided above.

  • In lines 2 through 18, the properties are userId, name, email, and age. We see that “email” is an object of type string, and it is a required field.
  • If email is a GSI (Global Secondary Index), that can be provided using an index object as an attribute. ( Lines 6 through 13 explain the method of declaring a GSI)
  • Creating a “user” instance of the User model and saving it using “”. This uses putItem and overwrites if there’s an existing record with the same primary key.

Querying the tables

Now that Dynamoose is imported and being used to create a User table, it is time to query it. Let us take an example of querying a user by giving an ID value.

If it’s a GSI-based search, it’s a different story. Dynamoose requires us to state which index to query and also the hash key of that index.

Here, assuming that email is the GSI and the index name is ‘EmailIndex’, this query returns records that match ‘’ from the email attribute. Using command (line 6), mentions which index is being used for the search.

Filter Expressions

Filter Expressions is a technique used in DynamoDB to filter data during scan or query operations. They are highly similar to WHERE clauses in SQL, but not entirely. They are checked against the returned results of the query. i.e.

  1. Retrieve the requested data.
  2. If there is a filter expression, it will run and remove the items that don’t match.
  3. Finally, return the data to the client.

To use filter expressions with Dynamoose, filter() is needed. Filter expects an attribute as a parameter and a condition trailing it.

We first get all the data using User.scan() (line 4) and filter them using age to get a subset of the returned data. In this case, we use gt() to filter users older than 25 and contains() to filter users in line 5. You can also use regular queries with a primary key or GSI and apply filters to them.


  1. DynamoDB Limitations: Dynamoose is built on top of AWS DynamoDB, so it inherits certain limitations from DynamoDB itself. Some notable limitations include a maximum item size of 400 KB, a maximum of 256 concurrent transactions per table, and a maximum of 20 global secondary indexes per table.
  2. Limited DynamoDB Features: Dynamoose aims to provide a simplified and intuitive interface for working with DynamoDB, but it may not support all advanced features and functionalities of DynamoDB. If you require fine-grained control over low-level DynamoDB operations, Dynamoose’s abstraction layer may limit your options.
  3. Performance Overhead: Dynamoose adds an additional layer of abstraction between your application and DynamoDB. While it provides convenience and higher-level operations, it may introduce a performance overhead compared to using DynamoDB directly for certain use cases that require maximum performance or low-latency operations.
  4. Community and Support: Dynamoose is not as widely adopted as some other ORMs or libraries for working with DynamoDB. Therefore, community support and available resources may be relatively limited compared to more established frameworks or libraries.
  5. Learning Curve: Although Dynamoose simplifies the interaction with DynamoDB, there is still a learning curve associated with understanding its syntax, APIs, and how they map to DynamoDB’s data model. It may take some time to become familiar with Dynamoose’s features and best practices.


A Node.js package called Dynamoose provides an easy-to-use interface for communicating with AWS DynamoDB. Working with DynamoDB is made simpler by its high-level API and automatic schema building. It provides features like type safety, data modeling, and support for transactions. However, it has a smaller community than other libraries and inherits some of DynamoDB’s restrictions. It may also cause performance overhead. Consider these things when choosing to use Dynamoose for your project.

August 18, 2023
min read
Subscribe to our newsletter
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
Share this article:

More articles