Skip to main content


A Table represents a one-to-one mappings to your DynamoDB table. They contain information about your table's name, primary keys, indexes, and more. They are also used to organize and coordinate operations between entities. Tables support a number of methods that allow you to interact with your entities including performing queries, scans, batch gets and batch writes.

Defining a Table

To define a new table, import it into your script:

import { Table } from 'dynamodb-toolbox'

const MyTable = new Table({
... // Table definition

Specifying Table Definitions

Table takes a single parameter of type object that accepts the following properties:

namestringyesThe name of your DynamoDB table (this will be used as the TableName property)
aliasstringnoAn optional alias to reference your table when using "batch" features
partitionKeystringyesThe attribute name of your table's partitionKey
sortKeystringnoThe attribute name of your table's sortKey
entityFieldboolean or stringnoDisables or overrides entity tracking field name (default: _et)
attributesobjectnoComplex type that optionally specifies the name and type of each attributes (see below)
indexesobjectnoComplex type that optionally specifies the name keys of your secondary indexes (see below)
autoExecutebooleannoEnables automatic execution of the DocumentClient method (default: true)
autoParsebooleannoEnables automatic parsing of returned data when autoExecute is true (default: true)
removeNullAttributesbooleannoRemoves null attributes instead of setting them to null (default: true)
DocumentClientDocumentClient*A valid instance of the AWS DocumentClient

* A Table can be instantiated without a DocumentClient, but most methods require it before execution

Table Attributes

The Table attributes property is an object that specifies the names and types of attributes associated with your DynamoDB table. This is an optional input that allows you to control attribute types. If an Entity object contains an attribute with the same name, but a different type, an error will be thrown. Each key in the object represents the attribute name and the value represents its DynamoDB type.

const MyTable = new Table({
attributes: {
pk: 'string',
sk: 'number',
attr1: 'list',
attr2: 'map',
attr3: 'boolean'
// ...

Valid DynamoDB types are: string, boolean, number, list, map, binary, or set.

Table Indexes

The indexes property is an object that specifies the names and keys of the secondary indexes on your DynamoDB table. Each key represents the index name and its value must contain an object with a partitionKey AND/OR a sortKey. partitionKeys and sortKeys require a value of type string that references an table attribute. If you use the same partitionKey as the table's partitionKey, or you only specify a sortKey, the library will recognize them as Local Secondary Indexes (LSIs). Otherwise, they will be Global Secondary Indexes (GSIs).

const MyTable = new Table({
indexes: {
GSI1: { partitionKey: 'GSI1pk', sortKey: 'GSI1sk' },
GSI2: { partitionKey: 'test' },
LSI1: { partitionKey: 'pk', sortKey: 'other_sk' },
LSI2: { sortKey: 'data' }
// ...

NOTE: The index name must match the index name on your table as it will be used in queries and other operations. The index must include the table's entityField attribute for automatic parsing of returned data.