Skip to main content

Quick Start

Install DynamoDB Toolbox

Using your favorite package manager, install DynamoDB Toolbox in your project by running one of the following commands:

# npm
npm i dynamodb-toolbox

# yarn
yarn add dynamodb-toolbox

Add to your code

The dynamodb-toolbox package exports Table and Entity classes. Import or require them into your code as follows:

const { Table, Entity } = require('dynamodb-toolbox')
import { Table, Entity } from 'dynamodb-toolbox'

Load the DocumentClient

import DynamoDB from 'aws-sdk/clients/dynamodb'

const DocumentClient = new DynamoDB.DocumentClient({
// Specify your client options as usual
convertEmptyValue: false

Define a Table

// Instantiate a table
const MyTable = new Table({
// Specify table name (used by DynamoDB)
name: 'my-table',

// Define partition and sort keys
partitionKey: 'pk',
sortKey: 'sk',

// Add the DocumentClient

Define an Entity

const Customer = new Entity({
// Specify entity name
name: 'Customer',

// Define attributes
attributes: {
id: { partitionKey: true }, // flag as partitionKey
sk: { hidden: true, sortKey: true }, // flag as sortKey and mark hidden
age: { type: 'number' }, // set the attribute type
name: { type: 'string', map: 'data' }, // map 'name' to table attribute 'data'
emailVerified: { type: 'boolean', required: true }, // specify attribute as required
co: { alias: 'company' }, // alias table attribute 'co' to 'company'
status: ['sk', 0], // composite key mapping
date_added: ['sk', 1] // composite key mapping

// Assign it to our table
table: MyTable

// In Typescript, the "as const" statement is needed for type inference
} as const)

Put an item

// Create an item (using table attribute names or aliases)
const customer = {
id: 123,
age: 35,
name: 'Jane Smith',
emailVerified: true,
company: 'ACME',
status: 'active',
date_added: '2020-04-24'

// Use the 'put' method of Customer:
await Customer.put(customer)

The item will be saved to DynamoDB like this:

"pk": 123,
"sk": "active#2020-04-24",
"age": 35,
"data": "Jane Smith",
"emailVerified": true,
"co": "ACME",
// Attributes auto-generated by DynamoDB-Toolbox
"_et": "customer", // Entity name (required for parsing)
"_ct": "2021-01-01T00:00:00.000Z", // Item creation date (optional)
"_md": "2021-01-01T00:00:00.000Z" // Item last modification date (optional)

Get an Item

// Specify primary key
const primaryKey = {
id: 123,
status: 'active',
date_added: '2020-04-24'

// Use the 'get' method of Customer
const response = await Customer.get(primaryKey)

Entity Type Inference

Since v0.4, the method inputs, options and response types are inferred from the Entity definition:

await Customer.put({
id: 123,
// ❌ Sort key is required ("sk" or both "status" and "date_added")
age: 35,
name: ['Jane', 'Smith'], // ❌ name should be a string
emailVerified: undefined, // ❌ attribute is marked as required
company: 'ACME'

const { Item: customer } = await Customer.get({
id: 123,
status: 'active',
date_added: '2020-04-24' // ✅ Valid primary key
type Customer = typeof customer
// 🙌 Type is equal to:
type ExpectedCustomer =
| {
id: any
age?: number | undefined
name?: string | undefined
emailVerified: boolean
company?: any
status: any
date_added: any
entity: string
created: string
modified: string
| undefined