Tables

Tables are the foundational building block when using Document Builder, following the Single Table design pattern.

Each instance of DynamoTable defined in your code should have a corresponding DynamoDB table in AWS.

Basic Usage

The only required parameters when defining a DynamoTable are the table name and a DynamoDBDocumentClient instance.

const dynamoDbClient = new DynamoDBClient();
const docClient = DynamoDBDocumentClient.from(dynamoDbClient);

const exampleTable = new DynamoTable({
  tableName: 'ExampleTable',
  documentClient: docClient,
});

Key Names

By default, Document Builder will assume that your table is using a composite primary key composed of a partition key named PK and a sort key named SK.

If your keys are named different, you can specify the names by passing the keyNames parameter when defining your table:

const exampleTable = new DynamoTable({
  tableName: 'ExampleTable',
  documentClient: docClient,
  keyNames: {
    partitionKey: 'PartitionKey',
    sortKey: 'SortKey',
  },
});

Simple Primary Key

If your table is using a simple primary key (aka only using a partition key), you can specify the sortKey as null to indicate that:

const exampleTable = new DynamoTable({
  tableName: 'ExampleTable',
  documentClient: docClient,
  keyNames: {
    partitionKey: 'PK',
    sortKey: null,
  },
});

Secondary Indexes

By default if you omit keyNames, Document Builder assumes your table only has a PK partition key and SK sort key with no secondary indexes. To define the names of secondary indexes, you can pass a globalSecondaryIndexes and/or localSecondaryIndexes object to the keyNames parameter:

const exampleTable = new DynamoTable({
  tableName: 'ExampleTable',
  documentClient: docClient,
  keyNames: {
    partitionKey: 'PK',
    sortKey: 'SK',
    globalSecondaryIndexes: {
      GSI1: {
        partitionKey: 'GSI1PK',
        sortKey: 'GSI1SK',
      },
      GSI2: {
        partitionKey: 'GSI2PK',
        // sortKey can be omitted if the GSI only has a partition key
      },
    },
    localSecondaryIndexes: {
      LSI1: {
        sortKey: 'LSI1SK',
      },
    },
  },
});

In the above example, GSI1, GSI2, and LSI1 are the names of your secondary indexes and are what you use when needing to refer to them elsewhere in your code.

Sending Table-Level Commands

In addition to entity-level operations executed via entity.send(), Document Builder supports table-level commands for operations that span multiple entity types in a single DynamoDB request. These commands are executed via table.send().

Use entity.prepare() to bind a batch or transaction command to a specific entity, then pass the prepared groups to a table command:

import { TableBatchWrite, TableBatchGet, BatchWrite, BatchGet } from 'dynamo-document-builder';

// Prepare each entity's batch operation
const userGroup = userEntity.prepare(new BatchWrite({
  items: [{ userId: 'u1', name: 'Alice', email: 'alice@example.com' }],
}));
const orderGroup = orderEntity.prepare(new BatchGet({
  keys: [{ orderId: 'o1' }, { orderId: 'o2' }],
}));

// Execute as a single DynamoDB request via table.send()
const { unprocessedPuts } = await myTable.send(new TableBatchWrite({
  writes: [userGroup, orderGroup],
}));

Document Builder provides four table-level commands:

TableBatchWrite — batch puts and deletes across multiple entity types
TableBatchGet — batch reads across multiple entity types
TableTransactWrite — atomic transactional writes across multiple entity types
TableTransactGet — transactional reads across multiple entity types

Tree-shakable Import

import { DynamoTable } from 'dynamo-document-builder/core/table';