class Table (construct)

Language	Type name
.NET	`Amazon.CDK.AWS.DynamoDB.Table`
Java	`software.amazon.awscdk.services.dynamodb.Table`
Python	`aws_cdk.aws_dynamodb.Table`
TypeScript (source)	`@aws-cdk/aws-dynamodb` » `Table`

Implements IConstruct, IConstruct, IDependable, IResource, ITable

Provides a DynamoDB table.

Example

const globalTable = new dynamodb.Table(this, 'Table', {
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING },
  replicationRegions: ['us-east-1', 'us-east-2', 'us-west-2'],
  billingMode: dynamodb.BillingMode.PROVISIONED,
});

globalTable.autoScaleWriteCapacity({
  minCapacity: 1,
  maxCapacity: 10,
}).scaleOnUtilization({ targetUtilizationPercent: 75 });

Initializer

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

Parameters

scope Construct
id string
props TableProps

Construct Props

Name	Type	Description
partitionKey	`Attribute`	Partition key attribute definition.
billingMode?	`BillingMode`	Specify how you are charged for read and write throughput and how you manage capacity.
contributorInsightsEnabled?	`boolean`	Whether CloudWatch contributor insights is enabled.
encryption?	`TableEncryption`	Whether server-side encryption with an AWS managed customer master key is enabled.
encryptionKey?	`IKey`	External KMS key to use for table encryption.
kinesisStream?	`IStream`	Kinesis Data Stream to capture item-level changes for the table.
pointInTimeRecovery?	`boolean`	Whether point-in-time recovery is enabled.
readCapacity?	`number`	The read capacity for the table.
removalPolicy?	`RemovalPolicy`	The removal policy to apply to the DynamoDB Table.
replicationRegions?	`string[]`	Regions where replica tables will be created.
replicationTimeout?	`Duration`	The timeout for a table replication operation in a single region.
serverSideEncryption?⚠️	`boolean`	Whether server-side encryption with an AWS managed customer master key is enabled.
sortKey?	`Attribute`	Sort key attribute definition.
stream?	`StreamViewType`	When an item in the table is modified, StreamViewType determines what information is written to the stream for this table.
tableClass?	`TableClass`	Specify the table class.
tableName?	`string`	Enforces a particular physical table name.
timeToLiveAttribute?	`string`	The name of TTL attribute.
waitForReplicationToFinish?	`boolean`	Indicates whether CloudFormation stack waits for replication to finish.
writeCapacity?	`number`	The write capacity for the table.

partitionKey

Type: Attribute

Partition key attribute definition.

billingMode?

Type: BillingMode (optional, default: PROVISIONED if replicationRegions is not specified, PAY_PER_REQUEST otherwise)

Specify how you are charged for read and write throughput and how you manage capacity.

contributorInsightsEnabled?

Type: boolean (optional, default: false)

Whether CloudWatch contributor insights is enabled.

encryption?

Type: TableEncryption (optional, default: server-side encryption is enabled with an AWS owned customer master key)

Whether server-side encryption with an AWS managed customer master key is enabled.

This property cannot be set if serverSideEncryption is set.

NOTE: if you set this to CUSTOMER_MANAGED and encryptionKey is not specified, the key that the Tablet generates for you will be created with default permissions. If you are using CDKv2, these permissions will be sufficient to enable the key for use with DynamoDB tables. If you are using CDKv1, make sure the feature flag @aws-cdk/aws-kms:defaultKeyPolicies is set to true in your cdk.json.

encryptionKey?

Type: IKey (optional, default: If encryption is set to TableEncryption.CUSTOMER_MANAGED and this property is undefined, a new KMS key will be created and associated with this table.)

External KMS key to use for table encryption.

This property can only be set if encryption is set to TableEncryption.CUSTOMER_MANAGED.

kinesisStream?

Type: IStream (optional, default: no Kinesis Data Stream)

Kinesis Data Stream to capture item-level changes for the table.

pointInTimeRecovery?

Type: boolean (optional, default: point-in-time recovery is disabled)

Whether point-in-time recovery is enabled.

readCapacity?

Type: number (optional, default: 5)

The read capacity for the table.

Careful if you add Global Secondary Indexes, as those will share the table's provisioned throughput.

Can only be provided if billingMode is Provisioned.

removalPolicy?

Type: RemovalPolicy (optional, default: RemovalPolicy.RETAIN)

The removal policy to apply to the DynamoDB Table.

replicationRegions?

Type: string[] (optional, default: no replica tables are created)

Regions where replica tables will be created.

replicationTimeout?

Type: Duration (optional, default: Duration.minutes(30))

The timeout for a table replication operation in a single region.

serverSideEncryption?⚠️

⚠️ Deprecated: This property is deprecated. In order to obtain the same behavior as enabling this, set the encryption property to TableEncryption.AWS_MANAGED instead.

Type: boolean (optional, default: server-side encryption is enabled with an AWS owned customer master key)

Whether server-side encryption with an AWS managed customer master key is enabled.

This property cannot be set if encryption and/or encryptionKey is set.

sortKey?

Type: Attribute (optional, default: no sort key)

Sort key attribute definition.

stream?

Type: StreamViewType (optional, default: streams are disabled unless replicationRegions is specified)

When an item in the table is modified, StreamViewType determines what information is written to the stream for this table.

tableClass?

Type: TableClass (optional, default: STANDARD)

Specify the table class.

tableName?

Type: string (optional, default: )

Enforces a particular physical table name.

timeToLiveAttribute?

Type: string (optional, default: TTL is disabled)

The name of TTL attribute.

waitForReplicationToFinish?

Type: boolean (optional, default: true)

Indicates whether CloudFormation stack waits for replication to finish.

If set to false, the CloudFormation resource will mark the resource as created and replication will be completed asynchronously. This property is ignored if replicationRegions property is not set.

DO NOT UNSET this property if adding/removing multiple replicationRegions in one deployment, as CloudFormation only supports one region replication at a time. CDK overcomes this limitation by waiting for replication to finish before starting new replicationRegion.

writeCapacity?

Type: number (optional, default: 5)

The write capacity for the table.

Careful if you add Global Secondary Indexes, as those will share the table's provisioned throughput.

Can only be provided if billingMode is Provisioned.

Properties

Name	Type	Description
env	`ResourceEnvironment`	The environment this resource belongs to.
hasIndex	`boolean`	Whether this table has indexes.
node	`ConstructNode`	The construct tree node associated with this construct.
regionalArns	`string[]`
stack	`Stack`	The stack in which this resource is defined.
tableArn	`string`	Arn of the dynamodb table.
tableName	`string`	Table name of the dynamodb table.
encryptionKey?	`IKey`	KMS encryption key, if this table uses a customer-managed encryption key.
tableStreamArn?	`string`	ARN of the table's stream, if there is one.

env

Type: ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

hasIndex

Type: boolean

Whether this table has indexes.

node

Type: ConstructNode

The construct tree node associated with this construct.

regionalArns

Type: string[]

stack

Type: Stack

The stack in which this resource is defined.

tableArn

Type: string

Arn of the dynamodb table.

tableName

Type: string

Table name of the dynamodb table.

encryptionKey?

Type: IKey (optional)

KMS encryption key, if this table uses a customer-managed encryption key.

tableStreamArn?

Type: string (optional)

ARN of the table's stream, if there is one.

Methods

Name	Description
addGlobalSecondaryIndex(props)	Add a global secondary index of table.
addLocalSecondaryIndex(props)	Add a local secondary index of table.
applyRemovalPolicy(policy)	Apply the given removal policy to this resource.
autoScaleGlobalSecondaryIndexReadCapacity(indexName, props)	Enable read capacity scaling for the given GSI.
autoScaleGlobalSecondaryIndexWriteCapacity(indexName, props)	Enable write capacity scaling for the given GSI.
autoScaleReadCapacity(props)	Enable read capacity scaling for this table.
autoScaleWriteCapacity(props)	Enable write capacity scaling for this table.
grant(grantee, ...actions)	Adds an IAM policy statement associated with this table to an IAM principal's policy.
grantFullAccess(grantee)	Permits all DynamoDB operations ("dynamodb:*") to an IAM principal.
grantReadData(grantee)	Permits an IAM principal all data read operations from this table: BatchGetItem, GetRecords, GetShardIterator, Query, GetItem, Scan, DescribeTable.
grantReadWriteData(grantee)	Permits an IAM principal to all data read/write operations to this table.
grantStream(grantee, ...actions)	Adds an IAM policy statement associated with this table's stream to an IAM principal's policy.
grantStreamRead(grantee)	Permits an IAM principal all stream data read operations for this table's stream: DescribeStream, GetRecords, GetShardIterator, ListStreams.
grantTableListStreams(grantee)	Permits an IAM Principal to list streams attached to current dynamodb table.
grantWriteData(grantee)	Permits an IAM principal all data write operations to this table: BatchWriteItem, PutItem, UpdateItem, DeleteItem, DescribeTable.
metric(metricName, props?)	Return the given named metric for this Table.
metricConditionalCheckFailedRequests(props?)	Metric for the conditional check failed requests this table.
metricConsumedReadCapacityUnits(props?)	Metric for the consumed read capacity units this table.
metricConsumedWriteCapacityUnits(props?)	Metric for the consumed write capacity units this table.
metricSuccessfulRequestLatency(props?)	Metric for the successful request latency this table.
metricSystemErrors(props?)⚠️	Metric for the system errors this table.
metricSystemErrorsForOperations(props?)	Metric for the system errors this table.
metricThrottledRequests(props?)⚠️	How many requests are throttled on this table.
metricThrottledRequestsForOperation(operation, props?)	How many requests are throttled on this table, for the given operation.
metricUserErrors(props?)	Metric for the user errors.
schema(indexName?)	Get schema attributes of table or index.
toString()	Returns a string representation of this construct.
protected validate()	Validate the table construct.
static fromTableArn(scope, id, tableArn)	Creates a Table construct that represents an external table via table arn.
static fromTableAttributes(scope, id, attrs)	Creates a Table construct that represents an external table.
static fromTableName(scope, id, tableName)	Creates a Table construct that represents an external table via table name.
static grantListStreams(grantee)⚠️	Permits an IAM Principal to list all DynamoDB Streams.

addGlobalSecondaryIndex(props)

public addGlobalSecondaryIndex(props: GlobalSecondaryIndexProps): void

Parameters

props GlobalSecondaryIndexProps — the property of global secondary index.

Add a global secondary index of table.

addLocalSecondaryIndex(props)

public addLocalSecondaryIndex(props: LocalSecondaryIndexProps): void

Parameters

props LocalSecondaryIndexProps — the property of local secondary index.

Add a local secondary index of table.

applyRemovalPolicy(policy)

public applyRemovalPolicy(policy: RemovalPolicy): void

Parameters

policy RemovalPolicy

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

autoScaleGlobalSecondaryIndexReadCapacity(indexName, props)

public autoScaleGlobalSecondaryIndexReadCapacity(indexName: string, props: EnableScalingProps): IScalableTableAttribute

Parameters

indexName string
props EnableScalingProps

Returns

IScalableTableAttribute

Enable read capacity scaling for the given GSI.

autoScaleGlobalSecondaryIndexWriteCapacity(indexName, props)

public autoScaleGlobalSecondaryIndexWriteCapacity(indexName: string, props: EnableScalingProps): IScalableTableAttribute

Parameters

indexName string
props EnableScalingProps

Returns

IScalableTableAttribute

Enable write capacity scaling for the given GSI.

autoScaleReadCapacity(props)

public autoScaleReadCapacity(props: EnableScalingProps): IScalableTableAttribute

Parameters

props EnableScalingProps

Returns

IScalableTableAttribute

Enable read capacity scaling for this table.

autoScaleWriteCapacity(props)

public autoScaleWriteCapacity(props: EnableScalingProps): IScalableTableAttribute

Parameters

props EnableScalingProps

Returns

IScalableTableAttribute

Enable write capacity scaling for this table.

grant(grantee, ...actions)

public grant(grantee: IGrantable, ...actions: string[]): Grant

Parameters

grantee IGrantable — The principal (no-op if undefined).
actions string — The set of actions to allow (i.e. "dynamodb:PutItem", "dynamodb:GetItem", ...).

Returns

Grant

Adds an IAM policy statement associated with this table to an IAM principal's policy.

If encryptionKey is present, appropriate grants to the key needs to be added separately using the table.encryptionKey.grant* methods.

grantFullAccess(grantee)

public grantFullAccess(grantee: IGrantable): Grant

Parameters

grantee IGrantable — The principal to grant access to.

Returns

Grant

Permits all DynamoDB operations ("dynamodb:*") to an IAM principal.

Appropriate grants will also be added to the customer-managed KMS key if one was configured.

grantReadData(grantee)

public grantReadData(grantee: IGrantable): Grant

Parameters

grantee IGrantable — The principal to grant access to.

Returns

Grant

Permits an IAM principal all data read operations from this table: BatchGetItem, GetRecords, GetShardIterator, Query, GetItem, Scan, DescribeTable.

Appropriate grants will also be added to the customer-managed KMS key if one was configured.

grantReadWriteData(grantee)

public grantReadWriteData(grantee: IGrantable): Grant

Parameters

grantee IGrantable — The principal to grant access to.

Returns

Grant

Permits an IAM principal to all data read/write operations to this table.

BatchGetItem, GetRecords, GetShardIterator, Query, GetItem, Scan, BatchWriteItem, PutItem, UpdateItem, DeleteItem, DescribeTable

Appropriate grants will also be added to the customer-managed KMS key if one was configured.

grantStream(grantee, ...actions)

public grantStream(grantee: IGrantable, ...actions: string[]): Grant

Parameters

grantee IGrantable — The principal (no-op if undefined).
actions string — The set of actions to allow (i.e. "dynamodb:DescribeStream", "dynamodb:GetRecords", ...).

Returns

Grant

Adds an IAM policy statement associated with this table's stream to an IAM principal's policy.

If encryptionKey is present, appropriate grants to the key needs to be added separately using the table.encryptionKey.grant* methods.

grantStreamRead(grantee)

public grantStreamRead(grantee: IGrantable): Grant

Parameters

grantee IGrantable — The principal to grant access to.

Returns

Grant

Permits an IAM principal all stream data read operations for this table's stream: DescribeStream, GetRecords, GetShardIterator, ListStreams.

Appropriate grants will also be added to the customer-managed KMS key if one was configured.

grantTableListStreams(grantee)

public grantTableListStreams(grantee: IGrantable): Grant

Parameters

grantee IGrantable — The principal (no-op if undefined).

Returns

Grant

Permits an IAM Principal to list streams attached to current dynamodb table.

grantWriteData(grantee)

public grantWriteData(grantee: IGrantable): Grant

Parameters

grantee IGrantable — The principal to grant access to.

Returns

Grant

Permits an IAM principal all data write operations to this table: BatchWriteItem, PutItem, UpdateItem, DeleteItem, DescribeTable.

Appropriate grants will also be added to the customer-managed KMS key if one was configured.

metric(metricName, props?)

public metric(metricName: string, props?: MetricOptions): Metric

Parameters

metricName string
props MetricOptions

Returns

Metric

Return the given named metric for this Table.

By default, the metric will be calculated as a sum over a period of 5 minutes. You can customize this by using the statistic and period properties.

metricConditionalCheckFailedRequests(props?)

public metricConditionalCheckFailedRequests(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

Metric for the conditional check failed requests this table.

By default, the metric will be calculated as a sum over a period of 5 minutes. You can customize this by using the statistic and period properties.

metricConsumedReadCapacityUnits(props?)

public metricConsumedReadCapacityUnits(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

Metric for the consumed read capacity units this table.

By default, the metric will be calculated as a sum over a period of 5 minutes. You can customize this by using the statistic and period properties.

metricConsumedWriteCapacityUnits(props?)

public metricConsumedWriteCapacityUnits(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

Metric for the consumed write capacity units this table.

By default, the metric will be calculated as a sum over a period of 5 minutes. You can customize this by using the statistic and period properties.

metricSuccessfulRequestLatency(props?)

public metricSuccessfulRequestLatency(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

Metric for the successful request latency this table.

By default, the metric will be calculated as an average over a period of 5 minutes. You can customize this by using the statistic and period properties.

metricSystemErrors(props?)⚠️

public metricSystemErrors(props?: MetricOptions): Metric

⚠️ Deprecated: use metricSystemErrorsForOperations.

Parameters

props MetricOptions

Returns

Metric

Metric for the system errors this table.

metricSystemErrorsForOperations(props?)

public metricSystemErrorsForOperations(props?: SystemErrorsForOperationsMetricOptions): IMetric

Parameters

props SystemErrorsForOperationsMetricOptions

Returns

IMetric

Metric for the system errors this table.

This will sum errors across all possible operations. Note that by default, each individual metric will be calculated as a sum over a period of 5 minutes. You can customize this by using the statistic and period properties.

metricThrottledRequests(props?)⚠️

public metricThrottledRequests(props?: MetricOptions): Metric

⚠️ Deprecated: Do not use this function. It returns an invalid metric. Use metricThrottledRequestsForOperation instead.

Parameters

props MetricOptions

Returns

Metric

How many requests are throttled on this table.

Default: sum over 5 minutes

metricThrottledRequestsForOperation(operation, props?)

public metricThrottledRequestsForOperation(operation: string, props?: MetricOptions): Metric

Parameters

operation string
props MetricOptions

Returns

Metric

How many requests are throttled on this table, for the given operation.

Default: sum over 5 minutes

metricUserErrors(props?)

public metricUserErrors(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

Metric for the user errors.

Note that this metric reports user errors across all the tables in the account and region the table resides in.

By default, the metric will be calculated as a sum over a period of 5 minutes. You can customize this by using the statistic and period properties.

schema(indexName?)

public schema(indexName?: string): SchemaOptions

Parameters

indexName string

Returns

SchemaOptions

Get schema attributes of table or index.

toString()

public toString(): string

Returns

string

Returns a string representation of this construct.

protected validate()

protected validate(): string[]

Returns

string[]

Validate the table construct.

static fromTableArn(scope, id, tableArn)

public static fromTableArn(scope: Construct, id: string, tableArn: string): ITable

Parameters

scope Construct — The parent creating construct (usually this).
id string — The construct's name.
tableArn string — The table's ARN.

Returns

ITable

Creates a Table construct that represents an external table via table arn.

static fromTableAttributes(scope, id, attrs)

public static fromTableAttributes(scope: Construct, id: string, attrs: TableAttributes): ITable

Parameters

scope Construct — The parent creating construct (usually this).
id string — The construct's name.
attrs TableAttributes — A TableAttributes object.

Returns

ITable

Creates a Table construct that represents an external table.

static fromTableName(scope, id, tableName)

public static fromTableName(scope: Construct, id: string, tableName: string): ITable

Parameters

scope Construct — The parent creating construct (usually this).
id string — The construct's name.
tableName string — The table's name.

Returns

ITable

Creates a Table construct that represents an external table via table name.

static grantListStreams(grantee)⚠️

public static grantListStreams(grantee: IGrantable): Grant

⚠️ Deprecated: Use {@link #grantTableListStreams} for more granular permission

Parameters

grantee IGrantable — The principal (no-op if undefined).

Returns

Grant

Permits an IAM Principal to list all DynamoDB Streams.