class Table (construct)

Language	Type name
.NET	`Amazon.CDK.AWS.DynamoDB.Table`
Go	`github.com/aws/aws-cdk-go/awscdk/v2/awsdynamodb#Table`
Java	`software.amazon.awscdk.services.dynamodb.Table`
Python	`aws_cdk.aws_dynamodb.Table`
TypeScript (source)	`aws-cdk-lib` » `aws_dynamodb` » `Table`

Implements IConstruct, IDependable, IResource, ITable, IResourceWithPolicy

Provides a DynamoDB table.

Example

import * as eventsources from 'aws-cdk-lib/aws-lambda-event-sources';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import { Key } from 'aws-cdk-lib/aws-kms';

declare const fn: lambda.Function;
const table = new dynamodb.Table(this, 'Table', {
  partitionKey: {
    name: 'id',
    type: dynamodb.AttributeType.STRING,
  },
  stream: dynamodb.StreamViewType.NEW_IMAGE,
});
// Your self managed KMS key
const myKey = Key.fromKeyArn(
  this,
  'SourceBucketEncryptionKey',
  'arn:aws:kms:us-east-1:123456789012:key/<key-id>',
);

fn.addEventSource(new eventsources.DynamoEventSource(table, {
  startingPosition: lambda.StartingPosition.LATEST,
  filters: [lambda.FilterCriteria.filter({ eventName: lambda.FilterRule.isEqual('INSERT') })],
  filterEncryption: myKey,
}));

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.
deletionProtection?	`boolean`	Enables deletion protection for the table.
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.
importSource?	`ImportSourceSpecification`	The properties of data being imported from the S3 bucket source to the table.
kinesisPrecisionTimestamp?	`ApproximateCreationDateTimePrecision`	Kinesis Data Stream approximate creation timestamp prescision.
kinesisStream?	`IStream`	Kinesis Data Stream to capture item-level changes for the table.
maxReadRequestUnits?	`number`	The maximum read request units for the table.
maxWriteRequestUnits?	`number`	The write request units 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.
resourcePolicy?	`PolicyDocument`	Resource policy to assign to table.
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`	[WARNING: Use this flag with caution, misusing this flag may cause deleting existing replicas, refer to the detailed documentation for more information] Indicates whether CloudFormation stack waits for replication to finish.
warmThroughput?	`WarmThroughput`	Specify values to pre-warm you DynamoDB Table Warm Throughput feature is not available for Global Table replicas using the `Table` construct.
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.

deletionProtection?

Type: boolean (optional, default: false)

Enables deletion protection for the table.

encryption?

Type: TableEncryption (optional, default: The table is encrypted with an encryption key managed by DynamoDB, and you are not charged any fee for using it.)

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. If encryption and this property are both undefined, then the table is encrypted with an encryption key managed by DynamoDB, and you are not charged any fee for using it.)

External KMS key to use for table encryption.

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

importSource?

Type: ImportSourceSpecification (optional, default: no data import from the S3 bucket)

The properties of data being imported from the S3 bucket source to the table.

kinesisPrecisionTimestamp?

Type: ApproximateCreationDateTimePrecision (optional, default: ApproximateCreationDateTimePrecision.MICROSECOND)

Kinesis Data Stream approximate creation timestamp prescision.

kinesisStream?

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

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

maxReadRequestUnits?

Type: number (optional, default: on-demand throughput is disabled)

The maximum read request units for the table.

Careful if you add Global Secondary Indexes, as those will share the table's maximum on-demand throughput.

Can only be provided if billingMode is PAY_PER_REQUEST.

maxWriteRequestUnits?

Type: number (optional, default: on-demand throughput is disabled)

The write request units for the table.

Careful if you add Global Secondary Indexes, as those will share the table's maximum on-demand throughput.

Can only be provided if billingMode is PAY_PER_REQUEST.

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.

resourcePolicy?

Type: PolicyDocument (optional, default: No resource policy statement)

Resource policy to assign to table.

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)

[WARNING: Use this flag with caution, misusing this flag may cause deleting existing replicas, refer to the detailed documentation for more information] 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.

WARNING: 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.

If the custom resource which handles replication has a physical resource ID with the format region instead of tablename-region (this would happen if the custom resource hasn't received an event since v1.91.0), DO NOT SET this property to false without making a change to the table name. This will cause the existing replicas to be deleted.

warmThroughput?

Type: WarmThroughput (optional, default: warm throughput is not configured)

Specify values to pre-warm you DynamoDB Table Warm Throughput feature is not available for Global Table replicas using the Table construct.

To enable Warm Throughput, use the TableV2 construct instead.

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	`Node`	The tree node.
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.
resourcePolicy?	`PolicyDocument`	Resource policy to assign to DynamoDB Table.
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: Node

The tree node.

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.

resourcePolicy?

Type: PolicyDocument (optional, default: No resource policy statements are added to the created table.)

Resource policy to assign to DynamoDB Table.

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.
addToResourcePolicy(statement)	Adds a statement to the resource policy associated with this file system.
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.
metricThrottledRequestsForOperations(props?)	How many requests are throttled on this table.
metricUserErrors(props?)	Metric for the user errors.
schema(indexName?)	Get schema attributes of table or index.
toString()	Returns a string representation of this 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.

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.

addToResourcePolicy(statement)

public addToResourcePolicy(statement: PolicyStatement): AddToResourcePolicyResult

Parameters

statement PolicyStatement — The policy statement to add.

Returns

AddToResourcePolicyResult

Adds a statement to the resource policy associated with this file system.

A resource policy will be automatically created upon the first call to addToResourcePolicy.

Note that this does not work with imported file systems.

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

metricThrottledRequestsForOperations(props?)

public metricThrottledRequestsForOperations(props?: OperationsMetricOptions): IMetric

Parameters

props OperationsMetricOptions

Returns

IMetric

How many requests are throttled on this table.

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.

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.