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

---

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.

See also: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-dynamodb-table.html#cfn-dynamodb-table-resourcepolicy

---

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.

See also: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-dynamodb-globaltable.html#cfn-dynamodb-globaltable-replicas

---

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.

See also: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-dynamodb-table-resourcepolicy.html

---

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.

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.

---

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.