The Table construct is a higher level CDK construct that makes it easy to create a DynamoDB table. It uses the following defaults:

• Defaults to using the On-Demand capacity to make it perfectly serverless.
• Enables Point-in-Time Recovery to make sure that you don't lose your data.
• Provides a nicer interface for defining indexes.

new Table(scope: Construct, id: string, props: TableProps)

Parameters

• scope Construct
• id string
• props TableProps

import { Table, TableFieldType } from "@serverless-stack/resources";

new Table(this, "Notes", {
  fields: {
    userId: TableFieldType.STRING,
    noteId: TableFieldType.STRING,
  },
  primaryIndex: { partitionKey: "noteId", sortKey: "userId" },
});

new Table(this, "Notes", {
  fields: {
    userId: TableFieldType.STRING,
    noteId: TableFieldType.STRING,
    time: TableFieldType.NUMBER,
  },
  primaryIndex: { partitionKey: "noteId", sortKey: "userId" },
  secondaryIndexes: {
    userTimeIndex: { partitionKey: "userId", sortKey: "time" },
  },
});

Configure the internally created CDK Table instance.

import { RemovalPolicy } from "@aws-cdk/core";

new Table(this, "Table", {
  fields: {
    userId: TableFieldType.STRING,
    noteId: TableFieldType.STRING,
  },
  primaryIndex: { partitionKey: "noteId", sortKey: "userId" },
  dynamodbTable: {
    removalPolicy: RemovalPolicy.DESTROY,
  },
});

Configure the internally created CDK GlobalSecondaryIndex.

import { ProjectionType } from "@aws-cdk/aws-dynamodb";

new Table(this, "Table", {
  fields: {
    userId: TableFieldType.STRING,
    noteId: TableFieldType.STRING,
    time: TableFieldType.NUMBER,
  },
  primaryIndex: { partitionKey: "noteId", sortKey: "userId" },
  secondaryIndexes: {
    userTimeIndex: {
      partitionKey: "userId",
      sortKey: "time",
      indexProps: {
        projectionType: ProjectionType.KEYS_ONLY,
      },
    },
  },
});

Enable DynamoDB Streams and add consumers.

const table = new Table(this, "Notes", {
  fields: {
    noteId: TableFieldType.STRING,
  },
  primaryIndex: { partitionKey: "noteId" },
  stream: true,
  consumers: {
    consumer1: "src/consumer1.main",
    consumer2: "src/consumer2.main",
  },
});

Lazily add the consumers after the table has been defined.

const table = new Table(this, "Notes", {
  fields: {
    noteId: TableFieldType.STRING,
  },
  primaryIndex: { partitionKey: "noteId" },
  stream: true,
});

table.addConsumers(this, {
  consumer1: "src/consumer1.main",
  consumer2: "src/consumer2.main",
});

You can extend the minimal config, to set some function props and have them apply to all the consumers.

new Table(this, "Notes", {
  defaultFunctionProps: {
    timeout: 20,
    environment: { topicName: topic.topicName },
    permissions: [topic],
  },
  stream: true,
  consumers: {
    consumer1: "src/consumer1.main",
    consumer2: "src/consumer2.main",
  }
});

If you wanted to configure each Lambda function separately, you can pass in the TableConsumerProps.

new Table(this, "Notes", {
  stream: true,
  consumers: {
    consumer1: {
      function: {
        handler: "src/consumer1.main",
        timeout: 10,
        environment: { topicName: topic.topicName },
        permissions: [topic],
      },
    }
  },
});

Note that, you can set the defaultFunctionProps while using the function per consumer. The function will just override the defaultFunctionProps. Except for the environment, the layers, and the permissions properties, that will be merged.

new Table(this, "Notes", {
  defaultFunctionProps: {
    timeout: 20,
    environment: { topicName: topic.topicName },
    permissions: [topic],
  },
  stream: true,
  consumers: {
    consumer1: {
      function: {
        handler: "src/consumer1.main",
        timeout: 10,
        environment: { bucketName: bucket.bucketName },
        permissions: [bucket],
      },
    },
    consumer2: "src/consumer2.main",
  },
});

So in the above example, the consumer1 function doesn't use the timeout that is set in the defaultFunctionProps. It'll instead use the one that is defined in the function definition (10 seconds). And the function will have both the topicName and the bucketName environment variables set; as well as permissions to both the topic and the bucket.

Allow the consumer functions to access S3.

const table = new Table(this, "Notes", {
  fields: {
    noteId: TableFieldType.STRING,
  },
  primaryIndex: { partitionKey: "noteId" },
  stream: true,
  consumers: {
    consumer1: "src/consumer1.main",
    consumer2: "src/consumer2.main",
  },
});

table.attachPermissions(["s3"]);

Allow the first consumer function to access S3.

const table = new Table(this, "Notes", {
  fields: {
    noteId: TableFieldType.STRING,
  },
  primaryIndex: { partitionKey: "noteId" },
  stream: true,
  consumers: {
    consumer1: "src/consumer1.main",
    consumer2: "src/consumer2.main",
  },
});

table.attachPermissionsToConsumer("consumer1", ["s3"]);

Configure the information that will be written to the Stream.

import { StreamViewType } from "@aws-cdk/aws-dynamodb";

new Table(this, "Notes", {
  fields: {
    noteId: TableFieldType.STRING,
  },
  primaryIndex: { partitionKey: "noteId" },
  stream: StreamViewType.NEW_IMAGE,
  consumers: {
    consumer1: "src/consumer1.main",
    consumer2: "src/consumer2.main",
  },
});

Configure the internally created CDK Event Source.

import { StartingPosition } from "@aws-cdk/aws-lambda";

new Table(this, "Notes", {
  fields: {
    noteId: TableFieldType.STRING,
  },
  primaryIndex: { partitionKey: "noteId" },
  stream: true,
  consumers: {
    consumer1: {
      function: "src/consumer1.main",
      consumerProps: {
        startingPosition: StartingPosition.TRIM_HORIZON,
      },
    },
  },
});

import { KinesisStream } from "@serverless-stack/resources";

const stream = new KinesisStream(this, "Stream");

const table = new Table(this, "Notes", {
  fields: {
    noteId: TableFieldType.STRING,
  },
  primaryIndex: { partitionKey: "noteId" },
  kinesisStream: stream,
});

Note, you do not need to configure the stream and consumers fields when enabling the Kinesis Streams. The stream field is used to configure DynamoDB Streams, and the consumers are only triggered by DyanmoDB Streams.

You can read more about configuring consumers for the Kinesis Stream in the KinesisStream doc.

Override the internally created CDK Table instance.

import * as dynamodb from "@aws-cdk/aws-dynamodb";

new Table(this, "Table", {
  dynamodbTable: dynamodb.Table.fromTableArn(this, "ImportedTable", tableArn),
});

The v0.21.0 release of the Table construct includes a small breaking change. You might be impacted by this change if:

• You are currently using any version < v0.21.0
• And using consumers with table Streams enabled

If you are configuring the consumers like so:

new Table(this, "Table", {
  consumers: [
    "src/consumerA.main",
    "src/consumerB.main",
  ],
});

Change it to:

import { StartingPosition } from "@aws-cdk/aws-lambda";

new Table(this, "Table", {
  consumers: {
    Consumer_0: {
      function: "src/consumerA.main",
      consumerProps: {
        startingPosition: StartingPosition.TRIM_HORIZON,
      },
    },
    Consumer_1: {
      function: "src/consumerB.main",
      consumerProps: {
        startingPosition: StartingPosition.TRIM_HORIZON,
      },
    }
  },
});

Note it is important to name the first consumer Consumer_0; the second consumer Consumer_1; and so on. This is to ensure CloudFormation recognizes them as the same consumers as before. Otherwise, CloudFormation will remove existing consumers and create new ones.

Also note the default starting position for the consumer has changed from TRIM_HORIZON to LATEST. Make sure to set the startingPosition in consumerProps if the default value was used before.

If you are making the addConsumers call like this:

table.addConsumers(this, [
  "src/consumer1.main",
  "src/consumer2.main",
]);

Change it to:

import * as cognito from "@aws-cdk/aws-cognito";

table.addConsumers(this, {
  Consumer_0: {
    function: "src/consumerA.main",
    consumerProps: {
      startingPosition: StartingPosition.TRIM_HORIZON,
    },
  },
  Consumer_1: {
    function: "src/consumerB.main",
    consumerProps: {
      startingPosition: StartingPosition.TRIM_HORIZON,
    },
  }
});

Read more about the TableConsumerProps.consumers below.

An instance of Table contains the following properties.

Type: string

The ARN of the internally created CDK Table instance.

Type: string

The name of the internally created CDK Table instance.

Type : cdk.aws-dynamodb.Table

The internally created CDK Table instance.

An instance of Table contains the following methods.

getFunction(consumerName: string): Function

Parameters

• consumerName string

Returns

• Function

Get the instance of the internally created Function, for a given consumer. Where the consumerName is the name used to define a consumer.

addConsumers(scope: cdk.Construct, consumers: { [consumerName: string]: FunctionDefinition | TableConsumerProps })

Parameters

• scope cdk.Construct
• consumers { [consumerName: string]: FunctionDefinition | TableConsumerProps }

An associative array with the consumer name being a string and the value is either a FunctionDefinition or the TableConsumerProps.

attachPermissions(permissions: Permissions)

Parameters

• permissions Permissions

Attaches the given list of permissions to all the consumerFunctions. This allows the consumers to access other AWS resources.

Internally calls Function.attachPermissions.

attachPermissions(consumerName: string, permissions: Permissions)

Parameters

• consumerName string

• permissions Permissions

Attaches the given list of permissions to a specific function in the list of consumerFunctions. This allows that consumer to access other AWS resources.

Internally calls Function.attachPermissions.

Type : { [key: string]: TableFieldType }

An associative array with the list of fields of the table. Where key is the name of the field and the value is one of TableFieldType.

Type : TableIndexProps

Define the primary index for the table using the TableIndexProps type.

Type : { [key: string]: TableIndexProps }, defaults to {}

An associative array of a list of secondary indexes, where the key is the name of the secondary index and the value is using the TableIndexProps type.

Type : boolean | cdk.aws-dynamodb.StreamViewType, defaults to false

DynamoDB Streams for the table. Takes a boolean or a cdk.aws-dynamodb.StreamViewType.

If stream is set to true, the Stream is enabled with NEW_AND_OLD_IMAGES.

Type : { [consumerName: string]: FunctionDefinition | TableConsumerProps }, defaults to {}

The consumers for this Stream. Takes an associative array, with the consumer name being a string and the value is either a FunctionDefinition or the TableConsumerProps.

:::caution You should not change the name of a consumer. :::

Note, if the consumerName is changed, CloudFormation will remove the existing consumer and create a new one. If the starting point is set to TRIM_HORIZON, all the historical records available in the Stream will be resent to the new consumer.

Type : KinesisStream, defaults to Kinesis Stream disabled

The Kinesis Stream for DynamoDB to Stream item-level changes in your table to.

Type : cdk.aws-dynamodb.Table | TableCdkProps, defaults to undefined

Or optionally pass in a CDK cdk.aws-dynamodb.Table instance or TableCdkProps. This allows you to override the default settings this construct uses internally to create the table.

Type : FunctionProps, defaults to {}

The default function props to be applied to all the Lambda functions in the Table. If the function is specified for a consumer, these default values are overridden. Except for the environment, the layers, and the permissions properties, that will be merged.

Used to define an index.

Type: string

The field that's to be used as a partition key for the index.

Type: string, defaults to undefined

The field that's to be used as the sort key for the index.

Type: TableCdkIndexProps, defaults to undefined

Or optionally pass in TableCdkIndexProps. This allows you to override the default settings this construct uses internally to create the index.

Type : FunctionDefinition

A FunctionDefinition object that'll be used to create the consumer function for the table.

Type : cdk.aws-lambda-event-sources.lambdaEventSources.DynamoEventSourceProps, defaults to DynamoEventSourceProps with starting point set to LATEST.

Or optionally pass in a CDK DynamoEventSourceProps. This allows you to override the default settings this construct uses internally to create the consumer.

TableCdkProps extends cdk.aws-dynamodb.TableProps with the exception that the partitionKey and sortKey fields are not accepted. The parition key and the sort key should be configured using the primaryIndex field.

You can use TableCdkProps to configure all the other table properties.

TableCdkIndexProps extends cdk.aws-dynamodb.GlobalSecondaryIndexProps with the exception that the indexName, partitionKey, and the sortKey fields are not accepted. The index name, parition key, and the sort key should be configured using the secondaryIndexes field.

You can use TableCdkIndexProps to configure the other index properties.

An enum with the following members representing the field types.

For example, to set a field as string, use sst.TableFieldType.STRING.