aws-cdk-lib.aws_dynamodb.Table

class Table (construct)

LanguageType name
.NETAmazon.CDK.AWS.DynamoDB.Table
Gogithub.com/aws/aws-cdk-go/awscdk/v2/awsdynamodb#Table
Javasoftware.amazon.awscdk.services.dynamodb.Table
Pythonaws_cdk.aws_dynamodb.Table
TypeScript (source)aws-cdk-lib » aws_dynamodb » Table

Implements IConstruct, IDependable, IResource, ITable

Provides a DynamoDB table.

Example

import * as cloudwatch from 'aws-cdk-lib/aws-cloudwatch';

const table = new dynamodb.Table(this, 'Table', {
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING },
});

const metric = table.metricThrottledRequestsForOperations({
  operations: [dynamodb.Operation.PUT_ITEM],
  period: Duration.minutes(1),
});

new cloudwatch.Alarm(this, 'Alarm', {
  metric: metric,
  evaluationPeriods: 1,
  threshold: 1,
});

Initializer

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

Parameters

  • scope Construct
  • id string
  • props TableProps

Construct Props

NameTypeDescription
partitionKeyAttributePartition key attribute definition.
billingMode?BillingModeSpecify how you are charged for read and write throughput and how you manage capacity.
contributorInsightsEnabled?booleanWhether CloudWatch contributor insights is enabled.
deletionProtection?booleanEnables deletion protection for the table.
encryption?TableEncryptionWhether server-side encryption with an AWS managed customer master key is enabled.
encryptionKey?IKeyExternal KMS key to use for table encryption.
kinesisStream?IStreamKinesis Data Stream to capture item-level changes for the table.
pointInTimeRecovery?booleanWhether point-in-time recovery is enabled.
readCapacity?numberThe read capacity for the table.
removalPolicy?RemovalPolicyThe removal policy to apply to the DynamoDB Table.
replicationRegions?string[]Regions where replica tables will be created.
replicationTimeout?DurationThe timeout for a table replication operation in a single region.
sortKey?AttributeSort key attribute definition.
stream?StreamViewTypeWhen an item in the table is modified, StreamViewType determines what information is written to the stream for this table.
tableClass?TableClassSpecify the table class.
tableName?stringEnforces a particular physical table name.
timeToLiveAttribute?stringThe name of TTL attribute.
waitForReplicationToFinish?booleanIndicates whether CloudFormation stack waits for replication to finish.
writeCapacity?numberThe 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.


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.


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.

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

NameTypeDescription
envResourceEnvironmentThe environment this resource belongs to.
hasIndexbooleanWhether this table has indexes.
nodeNodeThe tree node.
regionalArnsstring[]
stackStackThe stack in which this resource is defined.
tableArnstringArn of the dynamodb table.
tableNamestringTable name of the dynamodb table.
encryptionKey?IKeyKMS encryption key, if this table uses a customer-managed encryption key.
tableStreamArn?stringARN 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.


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

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


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.


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.