Package software.amazon.awscdk.services.dynamodb

package software.amazon.awscdk.services.dynamodb

Amazon DynamoDB Construct Library

The DynamoDB construct library has two table constructs - Table and TableV2. TableV2 is the preferred construct for all use cases, including creating a single table or a table with multiple replicas.

Table API documentation

Here is a minimal deployable DynamoDB table using TableV2: 

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .build();

By default, TableV2 will create a single table in the main deployment region referred to as the primary table. The properties of the primary table are configurable via TableV2 properties. For example, consider the following DynamoDB table created using the TableV2 construct defined in a Stack being deployed to us-west-2: 

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .contributorInsights(true)
         .tableClass(TableClass.STANDARD_INFREQUENT_ACCESS)
         .pointInTimeRecovery(true)
         .build();

The above TableV2 definition will result in the provisioning of a single table in us-west-2 with properties that match the properties set on the TableV2 instance.

Further reading: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GlobalTables.html

Replicas

The TableV2 construct can be configured with replica tables. This will enable you to work with your table as a global table. To do this, the TableV2 construct must be defined in a Stack with a defined region. The main deployment region must not be given as a replica because this is created by default with the TableV2 construct. The following is a minimal example of defining TableV2 with replicas. This TableV2 definition will provision three copies of the table - one in us-west-2 (primary deployment region), one in us-east-1, and one in us-east-2. 

 import software.amazon.awscdk.*;
 
 
 App app = new App();
 Stack stack = Stack.Builder.create(app, "Stack").env(Environment.builder().region("us-west-2").build()).build();
 
 TableV2 globalTable = TableV2.Builder.create(stack, "GlobalTable")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .replicas(List.of(ReplicaTableProps.builder().region("us-east-1").build(), ReplicaTableProps.builder().region("us-east-2").build()))
         .build();

Alternatively, you can add new replicas to an instance of the TableV2 construct using the addReplica method: 

 import software.amazon.awscdk.*;
 
 
 App app = new App();
 Stack stack = Stack.Builder.create(app, "Stack").env(Environment.builder().region("us-west-2").build()).build();
 
 TableV2 globalTable = TableV2.Builder.create(stack, "GlobalTable")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .replicas(List.of(ReplicaTableProps.builder().region("us-east-1").build()))
         .build();
 
 globalTable.addReplica(ReplicaTableProps.builder().region("us-east-2").deletionProtection(true).build());

The following properties are configurable on a per-replica basis, but will be inherited from the TableV2 properties if not specified:

  • contributorInsights
  • deletionProtection
  • pointInTimeRecovery
  • tableClass
  • readCapacity (only configurable if the TableV2 billing mode is PROVISIONED)
  • globalSecondaryIndexes (only contributorInsights and readCapacity)

The following example shows how to define properties on a per-replica basis: 

 import software.amazon.awscdk.*;
 
 
 App app = new App();
 Stack stack = Stack.Builder.create(app, "Stack").env(Environment.builder().region("us-west-2").build()).build();
 
 TableV2 globalTable = TableV2.Builder.create(stack, "GlobalTable")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .contributorInsights(true)
         .pointInTimeRecovery(true)
         .replicas(List.of(ReplicaTableProps.builder()
                 .region("us-east-1")
                 .tableClass(TableClass.STANDARD_INFREQUENT_ACCESS)
                 .pointInTimeRecovery(false)
                 .build(), ReplicaTableProps.builder()
                 .region("us-east-2")
                 .contributorInsights(false)
                 .build()))
         .build();

To obtain an ITableV2 reference to a specific replica table, call the replica method on an instance of the TableV2 construct and pass the replica region as an argument: 

 import software.amazon.awscdk.*;
 
 User user;
 
 
 public class FooStack extends Stack {
     public final TableV2 globalTable;
 
     public FooStack(Construct scope, String id, StackProps props) {
         super(scope, id, props);
 
         this.globalTable = TableV2.Builder.create(this, "GlobalTable")
                 .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
                 .replicas(List.of(ReplicaTableProps.builder().region("us-east-1").build(), ReplicaTableProps.builder().region("us-east-2").build()))
                 .build();
     }
 }
 
 public class BarStackProps extends StackProps {
     private ITableV2 replicaTable;
     public ITableV2 getReplicaTable() {
         return this.replicaTable;
     }
     public BarStackProps replicaTable(ITableV2 replicaTable) {
         this.replicaTable = replicaTable;
         return this;
     }
 }
 
 public class BarStack extends Stack {
     public BarStack(Construct scope, String id, BarStackProps props) {
         super(scope, id, props);
 
         // user is given grantWriteData permissions to replica in us-east-1
         props.replicaTable.grantWriteData(user);
     }
 }
 
 App app = new App();
 
 FooStack fooStack = FooStack.Builder.create(app, "FooStack").env(Environment.builder().region("us-west-2").build()).build();
 BarStack barStack = new BarStack(app, "BarStack", new BarStackProps()
         .replicaTable(fooStack.globalTable.replica("us-east-1"))
         .env(Environment.builder().region("us-east-1").build())
         );

Note: You can create an instance of the TableV2 construct with as many replicas as needed as long as there is only one replica per region. After table creation you can add or remove replicas, but you can only add or remove a single replica in each update.

Billing

The TableV2 construct can be configured with on-demand or provisioned billing:

  • On-demand - The default option. This is a flexible billing option capable of serving requests without capacity planning. The billing mode will be PAY_PER_REQUEST.
  • You can optionally specify the maxReadRequestUnits or maxWriteRequestUnits on individual tables and associated global secondary indexes (GSIs). When you configure maximum throughput for an on-demand table, throughput requests that exceed the maximum amount specified will be throttled.
  • Provisioned - Specify the readCapacity and writeCapacity that you need for your application. The billing mode will be PROVISIONED. Capacity can be configured using one of the following modes:

    • Fixed - provisioned throughput capacity is configured with a fixed number of I/O operations per second.
    • Autoscaled - provisioned throughput capacity is dynamically adjusted on your behalf in response to actual traffic patterns.

Note: writeCapacity can only be configured using autoscaled capacity.

The following example shows how to configure TableV2 with on-demand billing: 

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .billing(Billing.onDemand())
         .build();

The following example shows how to configure TableV2 with on-demand billing with optional maximum throughput configured: 

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .billing(Billing.onDemand(MaxThroughputProps.builder()
                 .maxReadRequestUnits(100)
                 .maxWriteRequestUnits(115)
                 .build()))
         .build();

When using provisioned billing, you must also specify readCapacity and writeCapacity. You can choose to configure readCapacity with fixed capacity or autoscaled capacity, but writeCapacity can only be configured with autoscaled capacity. The following example shows how to configure TableV2 with provisioned billing: 

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .billing(Billing.provisioned(ThroughputProps.builder()
                 .readCapacity(Capacity.fixed(10))
                 .writeCapacity(Capacity.autoscaled(AutoscaledCapacityOptions.builder().maxCapacity(15).build()))
                 .build()))
         .build();

When using provisioned billing, you can configure the readCapacity on a per-replica basis: 

 import software.amazon.awscdk.*;
 
 
 App app = new App();
 Stack stack = Stack.Builder.create(app, "Stack").env(Environment.builder().region("us-west-2").build()).build();
 
 TableV2 globalTable = TableV2.Builder.create(stack, "GlobalTable")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .billing(Billing.provisioned(ThroughputProps.builder()
                 .readCapacity(Capacity.fixed(10))
                 .writeCapacity(Capacity.autoscaled(AutoscaledCapacityOptions.builder().maxCapacity(15).build()))
                 .build()))
         .replicas(List.of(ReplicaTableProps.builder()
                 .region("us-east-1")
                 .build(), ReplicaTableProps.builder()
                 .region("us-east-2")
                 .readCapacity(Capacity.autoscaled(AutoscaledCapacityOptions.builder().maxCapacity(20).targetUtilizationPercent(50).build()))
                 .build()))
         .build();

When changing the billing for a table from provisioned to on-demand or from on-demand to provisioned, seedCapacity must be configured for each autoscaled resource: 

 TableV2 globalTable = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .billing(Billing.provisioned(ThroughputProps.builder()
                 .readCapacity(Capacity.fixed(10))
                 .writeCapacity(Capacity.autoscaled(AutoscaledCapacityOptions.builder().maxCapacity(10).seedCapacity(20).build()))
                 .build()))
         .build();

Further reading: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadWriteCapacityMode.html

Encryption

All user data stored in a DynamoDB table is fully encrypted at rest. When creating an instance of the TableV2 construct, you can select the following table encryption options:

  • AWS owned keys - Default encryption type. The keys are owned by DynamoDB (no additional charge).
  • AWS managed keys - The keys are stored in your account and are managed by AWS KMS (AWS KMS charges apply).
  • Customer managed keys - The keys are stored in your account and are created, owned, and managed by you. You have full control over the KMS keys (AWS KMS charges apply).

The following is an example of how to configure TableV2 with encryption using an AWS owned key: 

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .encryption(TableEncryptionV2.dynamoOwnedKey())
         .build();

The following is an example of how to configure TableV2 with encryption using an AWS managed key: 

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .encryption(TableEncryptionV2.awsManagedKey())
         .build();

When configuring TableV2 with encryption using customer managed keys, you must specify the KMS key for the primary table as the tableKey. A map of replicaKeyArns must be provided containing each replica region and the associated KMS key ARN: 

 import software.amazon.awscdk.*;
 import software.amazon.awscdk.services.kms.*;
 
 
 App app = new App();
 Stack stack = Stack.Builder.create(app, "Stack").env(Environment.builder().region("us-west-2").build()).build();
 
 Key tableKey = new Key(stack, "Key");
 Map<String, String> replicaKeyArns = Map.of(
         "us-east-1", "arn:aws:kms:us-east-1:123456789012:key/g24efbna-az9b-42ro-m3bp-cq249l94fca6",
         "us-east-2", "arn:aws:kms:us-east-2:123456789012:key/h90bkasj-bs1j-92wp-s2ka-bh857d60bkj8");
 
 TableV2 globalTable = TableV2.Builder.create(stack, "GlobalTable")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .encryption(TableEncryptionV2.customerManagedKey(tableKey, replicaKeyArns))
         .replicas(List.of(ReplicaTableProps.builder().region("us-east-1").build(), ReplicaTableProps.builder().region("us-east-2").build()))
         .build();

Note: When encryption is configured with customer managed keys, you must have a key already created in each replica region.

Further reading: https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-mgmt

Secondary Indexes

Secondary indexes allow efficient access to data with attributes other than the primaryKey. DynamoDB supports two types of secondary indexes:

  • Global secondary index - An index with a partitionKey and a sortKey that can be different from those on the base table. A globalSecondaryIndex is considered "global" because queries on the index can span all of the data in the base table, across all partitions. A globalSecondaryIndex is stored in its own partition space away from the base table and scales separately from the base table.
  • Local secondary index - An index that has the same partitionKey as the base table, but a different sortKey. A localSecondaryIndex is "local" in the sense that every partition of a localSecondaryIndex is scoped to a base table partition that has the same partitionKey value.

Further reading: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/SecondaryIndexes.html

Global Secondary Indexes

TableV2 can be configured with globalSecondaryIndexes by providing them as a TableV2 property: 

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .globalSecondaryIndexes(List.of(GlobalSecondaryIndexPropsV2.builder()
                 .indexName("gsi")
                 .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
                 .build()))
         .build();

Alternatively, you can add a globalSecondaryIndex using the addGlobalSecondaryIndex method: 

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .globalSecondaryIndexes(List.of(GlobalSecondaryIndexPropsV2.builder()
                 .indexName("gsi1")
                 .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
                 .build()))
         .build();
 
 table.addGlobalSecondaryIndex(GlobalSecondaryIndexPropsV2.builder()
         .indexName("gsi2")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .build());

You can configure readCapacity and writeCapacity on a globalSecondaryIndex when an TableV2 is configured with provisioned billing. If TableV2 is configured with provisioned billing but readCapacity or writeCapacity are not configured on a globalSecondaryIndex, then they will be inherited from the capacity settings specified with the billing configuration: 

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .billing(Billing.provisioned(ThroughputProps.builder()
                 .readCapacity(Capacity.fixed(10))
                 .writeCapacity(Capacity.autoscaled(AutoscaledCapacityOptions.builder().maxCapacity(10).build()))
                 .build()))
         .globalSecondaryIndexes(List.of(GlobalSecondaryIndexPropsV2.builder()
                 .indexName("gsi1")
                 .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
                 .readCapacity(Capacity.fixed(15))
                 .build(), GlobalSecondaryIndexPropsV2.builder()
                 .indexName("gsi2")
                 .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
                 .writeCapacity(Capacity.autoscaled(AutoscaledCapacityOptions.builder().minCapacity(5).maxCapacity(20).build()))
                 .build()))
         .build();

All globalSecondaryIndexes for replica tables are inherited from the primary table. You can configure contributorInsights and readCapacity for each globalSecondaryIndex on a per-replica basis: 

 import software.amazon.awscdk.*;
 
 
 App app = new App();
 Stack stack = Stack.Builder.create(app, "Stack").env(Environment.builder().region("us-west-2").build()).build();
 
 TableV2 globalTable = TableV2.Builder.create(stack, "GlobalTable")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .contributorInsights(true)
         .billing(Billing.provisioned(ThroughputProps.builder()
                 .readCapacity(Capacity.fixed(10))
                 .writeCapacity(Capacity.autoscaled(AutoscaledCapacityOptions.builder().maxCapacity(10).build()))
                 .build()))
         // each global secondary index will inherit contributor insights as true
         .globalSecondaryIndexes(List.of(GlobalSecondaryIndexPropsV2.builder()
                 .indexName("gsi1")
                 .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
                 .readCapacity(Capacity.fixed(15))
                 .build(), GlobalSecondaryIndexPropsV2.builder()
                 .indexName("gsi2")
                 .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
                 .writeCapacity(Capacity.autoscaled(AutoscaledCapacityOptions.builder().minCapacity(5).maxCapacity(20).build()))
                 .build()))
         .replicas(List.of(ReplicaTableProps.builder()
                 .region("us-east-1")
                 .globalSecondaryIndexOptions(Map.of(
                         "gsi1", ReplicaGlobalSecondaryIndexOptions.builder()
                                 .readCapacity(Capacity.autoscaled(AutoscaledCapacityOptions.builder().minCapacity(1).maxCapacity(10).build()))
                                 .build()))
                 .build(), ReplicaTableProps.builder()
                 .region("us-east-2")
                 .globalSecondaryIndexOptions(Map.of(
                         "gsi2", ReplicaGlobalSecondaryIndexOptions.builder()
                                 .contributorInsights(false)
                                 .build()))
                 .build()))
         .build();

Local Secondary Indexes

TableV2 can only be configured with localSecondaryIndexes when a sortKey is defined as a TableV2 property.

You can provide localSecondaryIndexes as a TableV2 property: 

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .sortKey(Attribute.builder().name("sk").type(AttributeType.NUMBER).build())
         .localSecondaryIndexes(List.of(LocalSecondaryIndexProps.builder()
                 .indexName("lsi")
                 .sortKey(Attribute.builder().name("sk").type(AttributeType.NUMBER).build())
                 .build()))
         .build();

Alternatively, you can add a localSecondaryIndex using the addLocalSecondaryIndex method: 

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .sortKey(Attribute.builder().name("sk").type(AttributeType.NUMBER).build())
         .localSecondaryIndexes(List.of(LocalSecondaryIndexProps.builder()
                 .indexName("lsi1")
                 .sortKey(Attribute.builder().name("sk").type(AttributeType.NUMBER).build())
                 .build()))
         .build();
 
 table.addLocalSecondaryIndex(LocalSecondaryIndexProps.builder()
         .indexName("lsi2")
         .sortKey(Attribute.builder().name("sk").type(AttributeType.NUMBER).build())
         .build());

Streams

Each DynamoDB table produces an independent stream based on all its writes, regardless of the origination point for those writes. DynamoDB supports two stream types:

  • DynamoDB streams - Capture item-level changes in your table, and push the changes to a DynamoDB stream. You then can access the change information through the DynamoDB Streams API.
  • Kinesis streams - Amazon Kinesis Data Streams for DynamoDB captures item-level changes in your table, and replicates the changes to a Kinesis data stream. You then can consume and manage the change information from Kinesis.

DynamoDB Streams

A dynamoStream can be configured as a TableV2 property. If the TableV2 instance has replica tables, then all replica tables will inherit the dynamoStream setting from the primary table. If replicas are configured, but dynamoStream is not configured, then the primary table and all replicas will be automatically configured with the NEW_AND_OLD_IMAGES stream view type. 

 import software.amazon.awscdk.*;
 import software.amazon.awscdk.services.kinesis.*;
 
 
 App app = new App();
 Stack stack = Stack.Builder.create(app, "Stack").env(Environment.builder().region("us-west-2").build()).build();
 
 TableV2 globalTable = TableV2.Builder.create(this, "GlobalTable")
         .partitionKey(Attribute.builder().name("id").type(AttributeType.STRING).build())
         .dynamoStream(StreamViewType.OLD_IMAGE)
         // tables in us-west-2, us-east-1, and us-east-2 all have dynamo stream type of OLD_IMAGES
         .replicas(List.of(ReplicaTableProps.builder().region("us-east-1").build(), ReplicaTableProps.builder().region("us-east-2").build()))
         .build();

Further reading: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Streams.html

Kinesis Streams

A kinesisStream can be configured as a TableV2 property. Replica tables will not inherit the kinesisStream configured for the primary table and should added on a per-replica basis. 

 import software.amazon.awscdk.*;
 import software.amazon.awscdk.services.kinesis.*;
 
 
 App app = new App();
 Stack stack = Stack.Builder.create(app, "Stack").env(Environment.builder().region("us-west-2").build()).build();
 
 Stream stream1 = new Stream(stack, "Stream1");
 IStream stream2 = Stream.fromStreamArn(stack, "Stream2", "arn:aws:kinesis:us-east-2:123456789012:stream/my-stream");
 
 TableV2 globalTable = TableV2.Builder.create(this, "GlobalTable")
         .partitionKey(Attribute.builder().name("id").type(AttributeType.STRING).build())
         .kinesisStream(stream1) // for table in us-west-2
         .replicas(List.of(ReplicaTableProps.builder().region("us-east-1").build(), ReplicaTableProps.builder()
                 .region("us-east-2")
                 .kinesisStream(stream2)
                 .build()))
         .build();

Further reading: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/kds.html

Keys

When an instance of the TableV2 construct is defined, you must define its schema using the partitionKey (required) and sortKey (optional) properties. 

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .sortKey(Attribute.builder().name("sk").type(AttributeType.NUMBER).build())
         .build();

Contributor Insights

Enabling contributorInsights for TableV2 will provide information about the most accessed and throttled items in a table or globalSecondaryIndex. DynamoDB delivers this information to you via CloudWatch Contributor Insights rules, reports, and graphs of report data. 

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .contributorInsights(true)
         .build();

Further reading: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/contributorinsights_HowItWorks.html

Deletion Protection

deletionProtection determines if your DynamoDB table is protected from deletion and is configurable as a TableV2 property. When enabled, the table cannot be deleted by any user or process. 

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .deletionProtection(true)
         .build();

You can also specify the removalPolicy as a property of the TableV2 construct. This property allows you to control what happens to tables provisioned using TableV2 during stack deletion. By default, the removalPolicy is RETAIN which will cause all tables provisioned using TableV2 to be retained in the account, but orphaned from the stack they were created in. You can also set the removalPolicy to DESTROY which will delete all tables created using TableV2 during stack deletion: 

 import software.amazon.awscdk.*;
 
 
 App app = new App();
 Stack stack = Stack.Builder.create(app, "Stack").env(Environment.builder().region("us-west-2").build()).build();
 
 TableV2 globalTable = TableV2.Builder.create(stack, "GlobalTable")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         // applys to all replicas, i.e., us-west-2, us-east-1, us-east-2
         .removalPolicy(RemovalPolicy.DESTROY)
         .replicas(List.of(ReplicaTableProps.builder().region("us-east-1").build(), ReplicaTableProps.builder().region("us-east-2").build()))
         .build();

deletionProtection is configurable on a per-replica basis. If the removalPolicy is set to DESTROY, but some replicas have deletionProtection enabled, then only the replicas without deletionProtection will be deleted during stack deletion: 

 import software.amazon.awscdk.*;
 
 
 App app = new App();
 Stack stack = Stack.Builder.create(app, "Stack").env(Environment.builder().region("us-west-2").build()).build();
 
 TableV2 globalTable = TableV2.Builder.create(stack, "GlobalTable")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .removalPolicy(RemovalPolicy.DESTROY)
         .deletionProtection(true)
         // only the replica in us-east-1 will be deleted during stack deletion
         .replicas(List.of(ReplicaTableProps.builder()
                 .region("us-east-1")
                 .deletionProtection(false)
                 .build(), ReplicaTableProps.builder()
                 .region("us-east-2")
                 .deletionProtection(true)
                 .build()))
         .build();

Point-in-Time Recovery

pointInTimeRecovery provides automatic backups of your DynamoDB table data which helps protect your tables from accidental write or delete operations. 

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .pointInTimeRecovery(true)
         .build();

Table Class

You can configure a TableV2 instance with table classes:

  • STANDARD - the default mode, and is recommended for the vast majority of workloads.
  • STANDARD_INFREQUENT_ACCESS - optimized for tables where storage is the dominant cost.

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .tableClass(TableClass.STANDARD_INFREQUENT_ACCESS)
         .build();

Further reading: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.TableClasses.html

Tags

You can add tags to a TableV2 in several ways. By adding the tags to the construct itself it will apply the tags to the primary table. 

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .tags(List.of(CfnTag.builder().key("primaryTableTagKey").value("primaryTableTagValue").build()))
         .build();

You can also add tags to replica tables by specifying them within the replica table properties. 

 TableV2 table = TableV2.Builder.create(this, "Table")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .replicas(List.of(ReplicaTableProps.builder()
                 .region("us-west-1")
                 .tags(List.of(CfnTag.builder().key("replicaTableTagKey").value("replicaTableTagValue").build()))
                 .build()))
         .build();

Referencing Existing Global Tables

To reference an existing DynamoDB table in your CDK application, use the TableV2.fromTableName, TableV2.fromTableArn, or TableV2.fromTableAttributes factory methods: 

 User user;
 
 
 ITableV2 table = TableV2.fromTableArn(this, "ImportedTable", "arn:aws:dynamodb:us-east-1:123456789012:table/my-table");
 // now you can call methods on the referenced table
 table.grantReadWriteData(user);

If you intend to use the tableStreamArn (including indirectly, for example by creating an aws-cdk-lib/aws-lambda-event-sources.DynamoEventSource on the referenced table), you must use the TableV2.fromTableAttributes method and the tableStreamArn property must be populated.

To grant permissions to indexes for a referenced table you can either set grantIndexPermissions to true, or you can provide the indexes via the globalIndexes or localIndexes properties. This will enable grant* methods to also grant permissions to all table indexes.

Resource Policy

Using resourcePolicy you can add a resource policy to a table in the form of a PolicyDocument: 

     // resource policy document
     const policy = new iam.PolicyDocument({
       statements: [
         new iam.PolicyStatement({
           actions: ['dynamodb:GetItem'],
           principals: [new iam.AccountRootPrincipal()],
           resources: ['*'],
         }),
       ],
     });
 
     // table with resource policy
     new dynamodb.TableV2(this, 'TableTestV2-1', {
       partitionKey: {
         name: 'id',
         type: dynamodb.AttributeType.STRING,
       },
       removalPolicy: RemovalPolicy.DESTROY,
       resourcePolicy: policy,
     });

TableV2 doesn’t support creating a replica and adding a resource-based policy to that replica in the same stack update in Regions other than the Region where you deploy the stack update. To incorporate a resource-based policy into a replica, you'll need to initially deploy the replica without the policy, followed by a subsequent update to include the desired policy.

Grants

Using any of the grant* methods on an instance of the TableV2 construct will only apply to the primary table, its indexes, and any associated encryptionKey. As an example, grantReadData used below will only apply the table in us-west-2: 

 import software.amazon.awscdk.*;
 import software.amazon.awscdk.services.kms.*;
 
 User user;
 
 
 App app = new App();
 Stack stack = Stack.Builder.create(app, "Stack").env(Environment.builder().region("us-west-2").build()).build();
 
 Key tableKey = new Key(stack, "Key");
 Map<String, String> replicaKeyArns = Map.of(
         "us-east-1", "arn:aws:kms:us-east-1:123456789012:key/g24efbna-az9b-42ro-m3bp-cq249l94fca6",
         "us-east-2", "arn:aws:kms:us-east-2:123456789012:key/g24efbna-az9b-42ro-m3bp-cq249l94fca6");
 
 TableV2 globalTable = TableV2.Builder.create(stack, "GlobalTable")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .encryption(TableEncryptionV2.customerManagedKey(tableKey, replicaKeyArns))
         .replicas(List.of(ReplicaTableProps.builder().region("us-east-1").build(), ReplicaTableProps.builder().region("us-east-2").build()))
         .build();
 
 // grantReadData only applys to the table in us-west-2 and the tableKey
 globalTable.grantReadData(user);

The replica method can be used to grant to a specific replica table: 

 import software.amazon.awscdk.*;
 import software.amazon.awscdk.services.kms.*;
 
 User user;
 
 
 App app = new App();
 Stack stack = Stack.Builder.create(app, "Stack").env(Environment.builder().region("us-west-2").build()).build();
 
 Key tableKey = new Key(stack, "Key");
 Map<String, String> replicaKeyArns = Map.of(
         "us-east-1", "arn:aws:kms:us-east-1:123456789012:key/g24efbna-az9b-42ro-m3bp-cq249l94fca6",
         "us-east-2", "arn:aws:kms:us-east-2:123456789012:key/g24efbna-az9b-42ro-m3bp-cq249l94fca6");
 
 TableV2 globalTable = TableV2.Builder.create(stack, "GlobalTable")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .encryption(TableEncryptionV2.customerManagedKey(tableKey, replicaKeyArns))
         .replicas(List.of(ReplicaTableProps.builder().region("us-east-1").build(), ReplicaTableProps.builder().region("us-east-2").build()))
         .build();
 
 // grantReadData applys to the table in us-east-2 and the key arn for the key in us-east-2
 globalTable.replica("us-east-2").grantReadData(user);

Metrics

You can use metric* methods to generate metrics for a table that can be used when configuring an Alarm or Graphs. The metric* methods only apply to the primary table provisioned using the TableV2 construct. As an example, metricConsumedReadCapacityUnits used below is only for the table in us-west-2: 

 import software.amazon.awscdk.*;
 import software.amazon.awscdk.services.cloudwatch.*;
 
 
 App app = new App();
 Stack stack = Stack.Builder.create(app, "Stack").env(Environment.builder().region("us-west-2").build()).build();
 
 TableV2 globalTable = TableV2.Builder.create(stack, "GlobalTable")
         .partitionKey(Attribute.builder().name("pk").type(AttributeType.STRING).build())
         .replicas(List.of(ReplicaTableProps.builder().region("us-east-1").build(), ReplicaTableProps.builder().region("us-east-2").build()))
         .build();
 
 // metric is only for the table in us-west-2
 Metric metric = globalTable.metricConsumedReadCapacityUnits();
 
 Alarm.Builder.create(this, "Alarm")
         .metric(metric)
         .evaluationPeriods(1)
         .threshold(1)
         .build();

The replica method can be used to generate a metric for a specific replica table: 

 import * as cdk form 'aws-cdk-lib';
 import * as cloudwatch from 'aws-cdk-lib/aws-cloudwatch';
 
 class FooStack extends cdk.Stack {
   public readonly globalTable: dynamodb.TableV2;
 
   public constructor(scope: Construct, id: string, props: cdk.StackProps) {
     super(scope, id, props);
 
     this.globalTable = new dynamodb.Tablev2(this, 'GlobalTable', {
       partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
       replicas: [
         { region: 'us-east-1' },
         { region: 'us-east-2' },
       ],
     });
   }
 }
 
 interface BarStack extends cdk.StackProps {
   readonly replicaTable: dynamodb.ITableV2;
 }
 
 class BarStack extends cdk.Stack {
   public constructor(scope: Construct, id: string, props: BarStackProps) {
     super(scope, id, props);
 
     // metric is only for the table in us-east-1
     const metric = props.replicaTable.metricConsumedReadCapacityUnits();
 
     new cloudwatch.Alarm(this, 'Alarm', {
       metric: metric,
       evaluationPeriods: 1,
       threshold: 1,
     });
   }
 }
 
 const app = new cdk.App();
 const fooStack = new FooStack(app, 'FooStack', { env: { region: 'us-west-2' } });
 const barStack = new BarStack(app, 'BarStack', {
   replicaTable: fooStack.globalTable.replica('us-east-1'),
   env: { region: 'us-east-1' },
 });

import from S3 Bucket

You can import data in S3 when creating a Table using the Table construct. To import data into DynamoDB, it is required that your data is in a CSV, DynamoDB JSON, or Amazon Ion format within an Amazon S3 bucket. The data may be compressed using ZSTD or GZIP formats, or you may choose to import it without compression. The data source can be a single S3 object or multiple S3 objects sharing a common prefix.

Further reading: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/S3DataImport.HowItWorks.html

use CSV format

The InputFormat.csv method accepts delimiter and headerList options as arguments. If delimiter is not specified, , is used by default. And if headerList is specified, the first line of CSV is treated as data instead of header. 

 import software.amazon.awscdk.*;
 import software.amazon.awscdk.services.s3.*;
 
 IBucket bucket;
 
 
 App app = new App();
 Stack stack = new Stack(app, "Stack");
 
 Table.Builder.create(stack, "Table")
         .partitionKey(Attribute.builder()
                 .name("id")
                 .type(AttributeType.STRING)
                 .build())
         .importSource(ImportSourceSpecification.builder()
                 .compressionType(InputCompressionType.GZIP)
                 .inputFormat(InputFormat.csv(CsvOptions.builder()
                         .delimiter(",")
                         .headerList(List.of("id", "name"))
                         .build()))
                 .bucket(bucket)
                 .keyPrefix("prefix")
                 .build())
         .build();

use DynamoDB JSON format

Use the InputFormat.dynamoDBJson() method to specify the inputFormat property. There are currently no options available. 

 import software.amazon.awscdk.*;
 import software.amazon.awscdk.services.s3.*;
 
 IBucket bucket;
 
 
 App app = new App();
 Stack stack = new Stack(app, "Stack");
 
 Table.Builder.create(stack, "Table")
         .partitionKey(Attribute.builder()
                 .name("id")
                 .type(AttributeType.STRING)
                 .build())
         .importSource(ImportSourceSpecification.builder()
                 .compressionType(InputCompressionType.GZIP)
                 .inputFormat(InputFormat.dynamoDBJson())
                 .bucket(bucket)
                 .keyPrefix("prefix")
                 .build())
         .build();

use Amazon Ion format

Use the InputFormat.ion() method to specify the inputFormat property. There are currently no options available. 

 import software.amazon.awscdk.*;
 import software.amazon.awscdk.services.s3.*;
 
 IBucket bucket;
 
 
 App app = new App();
 Stack stack = new Stack(app, "Stack");
 
 Table.Builder.create(stack, "Table")
         .partitionKey(Attribute.builder()
                 .name("id")
                 .type(AttributeType.STRING)
                 .build())
         .importSource(ImportSourceSpecification.builder()
                 .compressionType(InputCompressionType.GZIP)
                 .inputFormat(InputFormat.ion())
                 .bucket(bucket)
                 .keyPrefix("prefix")
                 .build())
         .build();