Amazon S3 Tables Construct Library
Version 2.274.0-alpha.0
Separate package
@aws-cdk/aws-s3tables-alpha is not part of aws-cdk-lib — install it separately:
sh
npm install @aws-cdk/aws-s3tables-alpha
pip install aws-cdk.aws-s3tables-alpha
This module is experimental (alpha): its API may change in any release, without a major version bump.
The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the Semantic Versioning model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.
Amazon S3 Tables
Amazon S3 Tables deliver the first cloud object store with built-in Apache Iceberg support and streamline storing tabular data at scale.
Usage
Define an S3 Table Bucket
ts
// Build a Table bucket
const sampleTableBucket = new TableBucket(scope, 'ExampleTableBucket', {
// optional fields:
tableBucketName: 'example-bucket-1', // if omitted, CDK generates a unique name that satisfies the S3 Tables naming rules
unreferencedFileRemoval: {
status: UnreferencedFileRemovalStatus.ENABLED,
noncurrentDays: 20,
unreferencedDays: 20,
}
});
python
from aws_cdk.aws_s3tables_alpha import UnreferencedFileRemoval
# Build a Table bucket
sample_table_bucket = TableBucket(scope, "ExampleTableBucket",
# optional fields:
table_bucket_name="example-bucket-1", # if omitted, CDK generates a unique name that satisfies the S3 Tables naming rules
unreferenced_file_removal=UnreferencedFileRemoval(
status=UnreferencedFileRemovalStatus.ENABLED,
noncurrent_days=20,
unreferenced_days=20
)
)
java
// Build a Table bucket
TableBucket sampleTableBucket = TableBucket.Builder.create(scope, "ExampleTableBucket")
// optional fields:
.tableBucketName("example-bucket-1") // if omitted, CDK generates a unique name that satisfies the S3 Tables naming rules
.unreferencedFileRemoval(UnreferencedFileRemoval.builder()
.status(UnreferencedFileRemovalStatus.ENABLED)
.noncurrentDays(20)
.unreferencedDays(20)
.build())
.build();
csharp
// Build a Table bucket
var sampleTableBucket = new TableBucket(scope, "ExampleTableBucket", new TableBucketProps {
// optional fields:
TableBucketName = "example-bucket-1", // if omitted, CDK generates a unique name that satisfies the S3 Tables naming rules
UnreferencedFileRemoval = new UnreferencedFileRemoval {
Status = UnreferencedFileRemovalStatus.ENABLED,
NoncurrentDays = 20,
UnreferencedDays = 20
}
});
go
// Build a Table bucket
sampleTableBucket := awscdkawss3tablesalpha.NewTableBucket(*scope, jsii.String("ExampleTableBucket"), &TableBucketProps{
// optional fields:
TableBucketName: jsii.String("example-bucket-1"),
// if omitted, CDK generates a unique name that satisfies the S3 Tables naming rules
UnreferencedFileRemoval: &UnreferencedFileRemoval{
Status: *awscdkawss3tablesalpha.UnreferencedFileRemovalStatus_ENABLED,
NoncurrentDays: jsii.Number(20),
UnreferencedDays: jsii.Number(20),
},
})
When tableBucketName is omitted, CDK derives the name from the stack name and the construct path. Because the path is part of the input, the generated name is not stable across stack or construct renames — renaming or moving the construct will produce a different name and replace the bucket. If you need a fixed, predictable name (for example, to reference the bucket from outside CDK or across separate deployments), pass tableBucketName explicitly.
Define an S3 Tables Namespace
ts
// Build a namespace
const sampleNamespace = new Namespace(scope, 'ExampleNamespace', {
namespaceName: 'example-namespace-1',
tableBucket: tableBucket,
});
python
# Build a namespace
sample_namespace = Namespace(scope, "ExampleNamespace",
namespace_name="example-namespace-1",
table_bucket=table_bucket
)
java
// Build a namespace
Namespace sampleNamespace = Namespace.Builder.create(scope, "ExampleNamespace")
.namespaceName("example-namespace-1")
.tableBucket(tableBucket)
.build();
csharp
// Build a namespace
var sampleNamespace = new Namespace(scope, "ExampleNamespace", new NamespaceProps {
NamespaceName = "example-namespace-1",
TableBucket = tableBucket
});
go
// Build a namespace
sampleNamespace := awscdkawss3tablesalpha.NewNamespace(*scope, jsii.String("ExampleNamespace"), &NamespaceProps{
NamespaceName: jsii.String("example-namespace-1"),
TableBucket: tableBucket,
})
Define an S3 Table
ts
// Build a table
const sampleTable = new Table(scope, 'ExampleTable', {
tableName: 'example_table',
namespace: namespace,
openTableFormat: OpenTableFormat.ICEBERG,
withoutMetadata: true,
});
// Build a table with an Iceberg Schema
const sampleTableWithSchema = new Table(scope, 'ExampleSchemaTable', {
tableName: 'example_table_with_schema',
namespace: namespace,
openTableFormat: OpenTableFormat.ICEBERG,
icebergMetadata: {
icebergSchema: {
schemaFieldList: [
{
name: 'id',
type: 'int',
required: true,
},
{
name: 'name',
type: 'string',
},
],
},
},
compaction: {
status: Status.ENABLED,
targetFileSizeMb: 128,
},
snapshotManagement: {
status: Status.ENABLED,
maxSnapshotAgeHours: 48,
minSnapshotsToKeep: 5,
},
});
python
from aws_cdk.aws_s3tables_alpha import IcebergMetadataProperty, IcebergSchemaProperty, SchemaFieldProperty, SchemaFieldProperty, CompactionProperty, SnapshotManagementProperty
# Build a table
sample_table = Table(scope, "ExampleTable",
table_name="example_table",
namespace=namespace,
open_table_format=OpenTableFormat.ICEBERG,
without_metadata=True
)
# Build a table with an Iceberg Schema
sample_table_with_schema = Table(scope, "ExampleSchemaTable",
table_name="example_table_with_schema",
namespace=namespace,
open_table_format=OpenTableFormat.ICEBERG,
iceberg_metadata=IcebergMetadataProperty(
iceberg_schema=IcebergSchemaProperty(
schema_field_list=[SchemaFieldProperty(
name="id",
type="int",
required=True
), SchemaFieldProperty(
name="name",
type="string"
)
]
)
),
compaction=CompactionProperty(
status=Status.ENABLED,
target_file_size_mb=128
),
snapshot_management=SnapshotManagementProperty(
status=Status.ENABLED,
max_snapshot_age_hours=48,
min_snapshots_to_keep=5
)
)
java
// Build a table
Table sampleTable = Table.Builder.create(scope, "ExampleTable")
.tableName("example_table")
.namespace(namespace)
.openTableFormat(OpenTableFormat.ICEBERG)
.withoutMetadata(true)
.build();
// Build a table with an Iceberg Schema
Table sampleTableWithSchema = Table.Builder.create(scope, "ExampleSchemaTable")
.tableName("example_table_with_schema")
.namespace(namespace)
.openTableFormat(OpenTableFormat.ICEBERG)
.icebergMetadata(IcebergMetadataProperty.builder()
.icebergSchema(IcebergSchemaProperty.builder()
.schemaFieldList(List.of(SchemaFieldProperty.builder()
.name("id")
.type("int")
.required(true)
.build(), SchemaFieldProperty.builder()
.name("name")
.type("string")
.build()))
.build())
.build())
.compaction(CompactionProperty.builder()
.status(Status.ENABLED)
.targetFileSizeMb(128)
.build())
.snapshotManagement(SnapshotManagementProperty.builder()
.status(Status.ENABLED)
.maxSnapshotAgeHours(48)
.minSnapshotsToKeep(5)
.build())
.build();
csharp
// Build a table
var sampleTable = new Table(scope, "ExampleTable", new TableProps {
TableName = "example_table",
Namespace = namespace,
OpenTableFormat = OpenTableFormat.ICEBERG,
WithoutMetadata = true
});
// Build a table with an Iceberg Schema
var sampleTableWithSchema = new Table(scope, "ExampleSchemaTable", new TableProps {
TableName = "example_table_with_schema",
Namespace = namespace,
OpenTableFormat = OpenTableFormat.ICEBERG,
IcebergMetadata = new IcebergMetadataProperty {
IcebergSchema = new IcebergSchemaProperty {
SchemaFieldList = new [] { new SchemaFieldProperty {
Name = "id",
Type = "int",
Required = true
}, new SchemaFieldProperty {
Name = "name",
Type = "string"
} }
}
},
Compaction = new CompactionProperty {
Status = Status.ENABLED,
TargetFileSizeMb = 128
},
SnapshotManagement = new SnapshotManagementProperty {
Status = Status.ENABLED,
MaxSnapshotAgeHours = 48,
MinSnapshotsToKeep = 5
}
});
go
// Build a table
sampleTable := awscdkawss3tablesalpha.NewTable(*scope, jsii.String("ExampleTable"), &TableProps{
TableName: jsii.String("example_table"),
Namespace: namespace,
OpenTableFormat: *awscdkawss3tablesalpha.OpenTableFormat_ICEBERG,
WithoutMetadata: jsii.Boolean(true),
})
// Build a table with an Iceberg Schema
sampleTableWithSchema := awscdkawss3tablesalpha.NewTable(*scope, jsii.String("ExampleSchemaTable"), &TableProps{
TableName: jsii.String("example_table_with_schema"),
Namespace: namespace,
OpenTableFormat: *awscdkawss3tablesalpha.OpenTableFormat_ICEBERG,
IcebergMetadata: &IcebergMetadataProperty{
IcebergSchema: &IcebergSchemaProperty{
SchemaFieldList: []SchemaFieldProperty{
&SchemaFieldProperty{
Name: jsii.String("id"),
Type: jsii.String("int"),
Required: jsii.Boolean(true),
},
&SchemaFieldProperty{
Name: jsii.String("name"),
Type: jsii.String("string"),
},
},
},
},
Compaction: &CompactionProperty{
Status: *awscdkawss3tablesalpha.Status_ENABLED,
TargetFileSizeMb: jsii.Number(128),
},
SnapshotManagement: &SnapshotManagementProperty{
Status: *awscdkawss3tablesalpha.Status_ENABLED,
MaxSnapshotAgeHours: jsii.Number(48),
MinSnapshotsToKeep: jsii.Number(5),
},
})
Learn more about table buckets maintenance operations and default behavior from the S3 Tables User Guide
Advanced Iceberg Table Configuration
You can configure partition specifications, sort orders, and table properties for optimized query performance.
The simplest way to add partitioning to your table:
ts
// Build a table with partition spec (minimal configuration)
const partitionedTable = new Table(scope, 'PartitionedTable', {
tableName: 'partitioned_table',
namespace: namespace,
openTableFormat: OpenTableFormat.ICEBERG,
icebergMetadata: {
icebergSchema: {
schemaFieldList: [
{ name: 'event_date', type: 'date', required: true },
{ name: 'event_name', type: 'string' },
],
},
icebergPartitionSpec: {
fields: [
{
sourceId: 1,
transform: IcebergTransform.IDENTITY,
name: 'date_partition',
},
],
},
},
});
python
from aws_cdk.aws_s3tables_alpha import IcebergMetadataProperty, IcebergSchemaProperty, SchemaFieldProperty, SchemaFieldProperty, IcebergPartitionSpec, IcebergPartitionField
# Build a table with partition spec (minimal configuration)
partitioned_table = Table(scope, "PartitionedTable",
table_name="partitioned_table",
namespace=namespace,
open_table_format=OpenTableFormat.ICEBERG,
iceberg_metadata=IcebergMetadataProperty(
iceberg_schema=IcebergSchemaProperty(
schema_field_list=[SchemaFieldProperty(name="event_date", type="date", required=True), SchemaFieldProperty(name="event_name", type="string")
]
),
iceberg_partition_spec=IcebergPartitionSpec(
fields=[IcebergPartitionField(
source_id=1,
transform=IcebergTransform.IDENTITY,
name="date_partition"
)
]
)
)
)
java
// Build a table with partition spec (minimal configuration)
Table partitionedTable = Table.Builder.create(scope, "PartitionedTable")
.tableName("partitioned_table")
.namespace(namespace)
.openTableFormat(OpenTableFormat.ICEBERG)
.icebergMetadata(IcebergMetadataProperty.builder()
.icebergSchema(IcebergSchemaProperty.builder()
.schemaFieldList(List.of(SchemaFieldProperty.builder().name("event_date").type("date").required(true).build(), SchemaFieldProperty.builder().name("event_name").type("string").build()))
.build())
.icebergPartitionSpec(IcebergPartitionSpec.builder()
.fields(List.of(IcebergPartitionField.builder()
.sourceId(1)
.transform(IcebergTransform.IDENTITY)
.name("date_partition")
.build()))
.build())
.build())
.build();
csharp
// Build a table with partition spec (minimal configuration)
var partitionedTable = new Table(scope, "PartitionedTable", new TableProps {
TableName = "partitioned_table",
Namespace = namespace,
OpenTableFormat = OpenTableFormat.ICEBERG,
IcebergMetadata = new IcebergMetadataProperty {
IcebergSchema = new IcebergSchemaProperty {
SchemaFieldList = new [] { new SchemaFieldProperty { Name = "event_date", Type = "date", Required = true }, new SchemaFieldProperty { Name = "event_name", Type = "string" } }
},
IcebergPartitionSpec = new IcebergPartitionSpec {
Fields = new [] { new IcebergPartitionField {
SourceId = 1,
Transform = IcebergTransform.IDENTITY,
Name = "date_partition"
} }
}
}
});
go
// Build a table with partition spec (minimal configuration)
partitionedTable := awscdkawss3tablesalpha.NewTable(*scope, jsii.String("PartitionedTable"), &TableProps{
TableName: jsii.String("partitioned_table"),
Namespace: namespace,
OpenTableFormat: *awscdkawss3tablesalpha.OpenTableFormat_ICEBERG,
IcebergMetadata: &IcebergMetadataProperty{
IcebergSchema: &IcebergSchemaProperty{
SchemaFieldList: []SchemaFieldProperty{
&SchemaFieldProperty{
Name: jsii.String("event_date"),
Type: jsii.String("date"),
Required: jsii.Boolean(true),
},
&SchemaFieldProperty{
Name: jsii.String("event_name"),
Type: jsii.String("string"),
},
},
},
IcebergPartitionSpec: &IcebergPartitionSpec{
Fields: []IcebergPartitionField{
&IcebergPartitionField{
SourceId: jsii.Number(1),
Transform: *awscdkawss3tablesalpha.IcebergTransform_IDENTITY(),
Name: jsii.String("date_partition"),
},
},
},
},
})
For full control, you can also configure sort orders and table properties:
ts
// Build a table with partition spec, sort order, and table properties
const advancedTable = new Table(scope, 'AdvancedTable', {
tableName: 'advanced_table',
namespace: namespace,
openTableFormat: OpenTableFormat.ICEBERG,
icebergMetadata: {
icebergSchema: {
schemaFieldList: [
{ id: 1, name: 'event_date', type: 'date', required: true },
{ id: 2, name: 'user_id', type: 'string', required: true },
],
},
icebergPartitionSpec: {
specId: 0,
fields: [
{
sourceId: 1,
transform: IcebergTransform.IDENTITY,
name: 'date_partition',
fieldId: 1000,
},
],
},
icebergSortOrder: {
orderId: 1,
fields: [
{
sourceId: 1,
transform: IcebergTransform.IDENTITY,
direction: SortDirection.ASC,
nullOrder: NullOrder.NULLS_LAST,
},
],
},
tableProperties: [
{ key: 'write.format.default', value: 'parquet' },
],
},
});
python
from aws_cdk.aws_s3tables_alpha import IcebergMetadataProperty, IcebergSchemaProperty, SchemaFieldProperty, SchemaFieldProperty, IcebergPartitionSpec, IcebergPartitionField, IcebergSortOrder, IcebergSortField, TablePropertyEntry
# Build a table with partition spec, sort order, and table properties
advanced_table = Table(scope, "AdvancedTable",
table_name="advanced_table",
namespace=namespace,
open_table_format=OpenTableFormat.ICEBERG,
iceberg_metadata=IcebergMetadataProperty(
iceberg_schema=IcebergSchemaProperty(
schema_field_list=[SchemaFieldProperty(id=1, name="event_date", type="date", required=True), SchemaFieldProperty(id=2, name="user_id", type="string", required=True)
]
),
iceberg_partition_spec=IcebergPartitionSpec(
spec_id=0,
fields=[IcebergPartitionField(
source_id=1,
transform=IcebergTransform.IDENTITY,
name="date_partition",
field_id=1000
)
]
),
iceberg_sort_order=IcebergSortOrder(
order_id=1,
fields=[IcebergSortField(
source_id=1,
transform=IcebergTransform.IDENTITY,
direction=SortDirection.ASC,
null_order=NullOrder.NULLS_LAST
)
]
),
table_properties=[TablePropertyEntry(key="write.format.default", value="parquet")
]
)
)
java
// Build a table with partition spec, sort order, and table properties
Table advancedTable = Table.Builder.create(scope, "AdvancedTable")
.tableName("advanced_table")
.namespace(namespace)
.openTableFormat(OpenTableFormat.ICEBERG)
.icebergMetadata(IcebergMetadataProperty.builder()
.icebergSchema(IcebergSchemaProperty.builder()
.schemaFieldList(List.of(SchemaFieldProperty.builder().id(1).name("event_date").type("date").required(true).build(), SchemaFieldProperty.builder().id(2).name("user_id").type("string").required(true).build()))
.build())
.icebergPartitionSpec(IcebergPartitionSpec.builder()
.specId(0)
.fields(List.of(IcebergPartitionField.builder()
.sourceId(1)
.transform(IcebergTransform.IDENTITY)
.name("date_partition")
.fieldId(1000)
.build()))
.build())
.icebergSortOrder(IcebergSortOrder.builder()
.orderId(1)
.fields(List.of(IcebergSortField.builder()
.sourceId(1)
.transform(IcebergTransform.IDENTITY)
.direction(SortDirection.ASC)
.nullOrder(NullOrder.NULLS_LAST)
.build()))
.build())
.tableProperties(List.of(TablePropertyEntry.builder().key("write.format.default").value("parquet").build()))
.build())
.build();
csharp
// Build a table with partition spec, sort order, and table properties
var advancedTable = new Table(scope, "AdvancedTable", new TableProps {
TableName = "advanced_table",
Namespace = namespace,
OpenTableFormat = OpenTableFormat.ICEBERG,
IcebergMetadata = new IcebergMetadataProperty {
IcebergSchema = new IcebergSchemaProperty {
SchemaFieldList = new [] { new SchemaFieldProperty { Id = 1, Name = "event_date", Type = "date", Required = true }, new SchemaFieldProperty { Id = 2, Name = "user_id", Type = "string", Required = true } }
},
IcebergPartitionSpec = new IcebergPartitionSpec {
SpecId = 0,
Fields = new [] { new IcebergPartitionField {
SourceId = 1,
Transform = IcebergTransform.IDENTITY,
Name = "date_partition",
FieldId = 1000
} }
},
IcebergSortOrder = new IcebergSortOrder {
OrderId = 1,
Fields = new [] { new IcebergSortField {
SourceId = 1,
Transform = IcebergTransform.IDENTITY,
Direction = SortDirection.ASC,
NullOrder = NullOrder.NULLS_LAST
} }
},
TableProperties = new [] { new TablePropertyEntry { Key = "write.format.default", Value = "parquet" } }
}
});
go
// Build a table with partition spec, sort order, and table properties
advancedTable := awscdkawss3tablesalpha.NewTable(*scope, jsii.String("AdvancedTable"), &TableProps{
TableName: jsii.String("advanced_table"),
Namespace: namespace,
OpenTableFormat: *awscdkawss3tablesalpha.OpenTableFormat_ICEBERG,
IcebergMetadata: &IcebergMetadataProperty{
IcebergSchema: &IcebergSchemaProperty{
SchemaFieldList: []SchemaFieldProperty{
&SchemaFieldProperty{
Id: jsii.Number(1),
Name: jsii.String("event_date"),
Type: jsii.String("date"),
Required: jsii.Boolean(true),
},
&SchemaFieldProperty{
Id: jsii.Number(2),
Name: jsii.String("user_id"),
Type: jsii.String("string"),
Required: jsii.Boolean(true),
},
},
},
IcebergPartitionSpec: &IcebergPartitionSpec{
SpecId: jsii.Number(0),
Fields: []IcebergPartitionField{
&IcebergPartitionField{
SourceId: jsii.Number(1),
Transform: *awscdkawss3tablesalpha.IcebergTransform_IDENTITY(),
Name: jsii.String("date_partition"),
FieldId: jsii.Number(1000),
},
},
},
IcebergSortOrder: &IcebergSortOrder{
OrderId: jsii.Number(1),
Fields: []IcebergSortField{
&IcebergSortField{
SourceId: jsii.Number(1),
Transform: *awscdkawss3tablesalpha.IcebergTransform_IDENTITY(),
Direction: *awscdkawss3tablesalpha.SortDirection_ASC,
NullOrder: *awscdkawss3tablesalpha.NullOrder_NULLS_LAST,
},
},
},
TableProperties: []TablePropertyEntry{
&TablePropertyEntry{
Key: jsii.String("write.format.default"),
Value: jsii.String("parquet"),
},
},
},
})
Controlling Table Bucket Permissions
ts
// Grant the principal read permissions to the bucket and all tables within
const accountId = '123456789012'
tableBucket.grantRead(new iam.AccountPrincipal(accountId), '*');
// Grant the role write permissions to the bucket and all tables within
const role = new iam.Role(stack, 'MyRole', { assumedBy: new iam.ServicePrincipal('sample') });
tableBucket.grantWrite(role, '*');
// Grant the user read and write permissions to the bucket and all tables within
tableBucket.grantReadWrite(new iam.User(stack, 'MyUser'), '*');
// Grant permissions to the bucket and a particular table within it
const tableId = '6ba046b2-26de-44cf-9144-0c7862593a7b'
tableBucket.grantReadWrite(new iam.AccountPrincipal(accountId), tableId);
// Add custom resource policy statements
const permissions = new iam.PolicyStatement({
effect: iam.Effect.ALLOW,
actions: ['s3tables:*'],
principals: [ new iam.ServicePrincipal('example.aws.internal') ],
resources: ['*']
});
tableBucket.addToResourcePolicy(permissions);
python
# Grant the principal read permissions to the bucket and all tables within
account_id = "123456789012"
table_bucket.grant_read(iam.AccountPrincipal(account_id), "*")
# Grant the role write permissions to the bucket and all tables within
role = iam.Role(stack, "MyRole", assumed_by=iam.ServicePrincipal("sample"))
table_bucket.grant_write(role, "*")
# Grant the user read and write permissions to the bucket and all tables within
table_bucket.grant_read_write(iam.User(stack, "MyUser"), "*")
# Grant permissions to the bucket and a particular table within it
table_id = "6ba046b2-26de-44cf-9144-0c7862593a7b"
table_bucket.grant_read_write(iam.AccountPrincipal(account_id), table_id)
# Add custom resource policy statements
permissions = iam.PolicyStatement(
effect=iam.Effect.ALLOW,
actions=["s3tables:*"],
principals=[iam.ServicePrincipal("example.aws.internal")],
resources=["*"]
)
table_bucket.add_to_resource_policy(permissions)
java
// Grant the principal read permissions to the bucket and all tables within
String accountId = "123456789012";
tableBucket.grantRead(new AccountPrincipal(accountId), "*");
// Grant the role write permissions to the bucket and all tables within
Role role = Role.Builder.create(stack, "MyRole").assumedBy(new ServicePrincipal("sample")).build();
tableBucket.grantWrite(role, "*");
// Grant the user read and write permissions to the bucket and all tables within
tableBucket.grantReadWrite(new User(stack, "MyUser"), "*");
// Grant permissions to the bucket and a particular table within it
String tableId = "6ba046b2-26de-44cf-9144-0c7862593a7b";
tableBucket.grantReadWrite(new AccountPrincipal(accountId), tableId);
// Add custom resource policy statements
PolicyStatement permissions = PolicyStatement.Builder.create()
.effect(Effect.ALLOW)
.actions(List.of("s3tables:*"))
.principals(List.of(new ServicePrincipal("example.aws.internal")))
.resources(List.of("*"))
.build();
tableBucket.addToResourcePolicy(permissions);
csharp
// Grant the principal read permissions to the bucket and all tables within
var accountId = "123456789012";
tableBucket.GrantRead(new AccountPrincipal(accountId), "*");
// Grant the role write permissions to the bucket and all tables within
var role = new Role(stack, "MyRole", new RoleProps { AssumedBy = new ServicePrincipal("sample") });
tableBucket.GrantWrite(role, "*");
// Grant the user read and write permissions to the bucket and all tables within
tableBucket.GrantReadWrite(new User(stack, "MyUser"), "*");
// Grant permissions to the bucket and a particular table within it
var tableId = "6ba046b2-26de-44cf-9144-0c7862593a7b";
tableBucket.GrantReadWrite(new AccountPrincipal(accountId), tableId);
// Add custom resource policy statements
var permissions = new PolicyStatement(new PolicyStatementProps {
Effect = Effect.ALLOW,
Actions = new [] { "s3tables:*" },
Principals = new [] { new ServicePrincipal("example.aws.internal") },
Resources = new [] { "*" }
});
tableBucket.AddToResourcePolicy(permissions);
go
// Grant the principal read permissions to the bucket and all tables within
accountId := "123456789012"
tableBucket.grantRead(iam.NewAccountPrincipal(accountId), jsii.String("*"))
// Grant the role write permissions to the bucket and all tables within
role := iam.NewRole(stack, jsii.String("MyRole"), &RoleProps{
AssumedBy: iam.NewServicePrincipal(jsii.String("sample")),
})
tableBucket.grantWrite(role, jsii.String("*"))
// Grant the user read and write permissions to the bucket and all tables within
tableBucket.grantReadWrite(iam.NewUser(stack, jsii.String("MyUser")), jsii.String("*"))
// Grant permissions to the bucket and a particular table within it
tableId := "6ba046b2-26de-44cf-9144-0c7862593a7b"
tableBucket.grantReadWrite(iam.NewAccountPrincipal(accountId), tableId)
// Add custom resource policy statements
permissions := iam.NewPolicyStatement(&PolicyStatementProps{
Effect: iam.Effect_ALLOW,
Actions: []*string{
jsii.String("s3tables:*"),
},
Principals: []IPrincipal{
iam.NewServicePrincipal(jsii.String("example.aws.internal")),
},
Resources: []*string{
jsii.String("*"),
},
})
tableBucket.addToResourcePolicy(permissions)
Controlling Table Bucket Encryption Settings
S3 TableBuckets have SSE (server-side encryption with AES-256) enabled by default with S3 managed keys. You can also bring your own KMS key for KMS-SSE or have S3 create a KMS key for you.
If a bucket is encrypted with KMS, grant functions on the bucket will also grant access to the TableBucket's associated KMS key.
ts
// Provide a user defined KMS Key:
const key = new kms.Key(scope, 'UserKey', {});
const encryptedBucket = new TableBucket(scope, 'EncryptedTableBucket', {
tableBucketName: 'table-bucket-1',
encryption: TableBucketEncryption.KMS,
encryptionKey: key,
});
// This account principal will also receive kms:Decrypt access to the KMS key
encryptedBucket.grantRead(new iam.AccountPrincipal('123456789012'), '*');
// Use S3 managed server side encryption (default)
const encryptedBucketDefault = new TableBucket(scope, 'EncryptedTableBucketDefault', {
tableBucketName: 'table-bucket-3',
encryption: TableBucketEncryption.S3_MANAGED, // Uses AES-256 encryption by default
});
python
# Provide a user defined KMS Key:
key = kms.Key(scope, "UserKey")
encrypted_bucket = TableBucket(scope, "EncryptedTableBucket",
table_bucket_name="table-bucket-1",
encryption=TableBucketEncryption.KMS,
encryption_key=key
)
# This account principal will also receive kms:Decrypt access to the KMS key
encrypted_bucket.grant_read(iam.AccountPrincipal("123456789012"), "*")
# Use S3 managed server side encryption (default)
encrypted_bucket_default = TableBucket(scope, "EncryptedTableBucketDefault",
table_bucket_name="table-bucket-3",
encryption=TableBucketEncryption.S3_MANAGED
)
java
// Provide a user defined KMS Key:
Key key = Key.Builder.create(scope, "UserKey").build();
TableBucket encryptedBucket = TableBucket.Builder.create(scope, "EncryptedTableBucket")
.tableBucketName("table-bucket-1")
.encryption(TableBucketEncryption.KMS)
.encryptionKey(key)
.build();
// This account principal will also receive kms:Decrypt access to the KMS key
encryptedBucket.grantRead(new AccountPrincipal("123456789012"), "*");
// Use S3 managed server side encryption (default)
TableBucket encryptedBucketDefault = TableBucket.Builder.create(scope, "EncryptedTableBucketDefault")
.tableBucketName("table-bucket-3")
.encryption(TableBucketEncryption.S3_MANAGED)
.build();
csharp
// Provide a user defined KMS Key:
var key = new Key(scope, "UserKey", new KeyProps { });
var encryptedBucket = new TableBucket(scope, "EncryptedTableBucket", new TableBucketProps {
TableBucketName = "table-bucket-1",
Encryption = TableBucketEncryption.KMS,
EncryptionKey = key
});
// This account principal will also receive kms:Decrypt access to the KMS key
encryptedBucket.GrantRead(new AccountPrincipal("123456789012"), "*");
// Use S3 managed server side encryption (default)
var encryptedBucketDefault = new TableBucket(scope, "EncryptedTableBucketDefault", new TableBucketProps {
TableBucketName = "table-bucket-3",
Encryption = TableBucketEncryption.S3_MANAGED
});
go
// Provide a user defined KMS Key:
key := kms.NewKey(*scope, jsii.String("UserKey"), &KeyProps{
})
encryptedBucket := awscdkawss3tablesalpha.NewTableBucket(*scope, jsii.String("EncryptedTableBucket"), &TableBucketProps{
TableBucketName: jsii.String("table-bucket-1"),
Encryption: *awscdkawss3tablesalpha.TableBucketEncryption_KMS,
EncryptionKey: key,
})
// This account principal will also receive kms:Decrypt access to the KMS key
encryptedBucket.grantRead(iam.NewAccountPrincipal(jsii.String("123456789012")), jsii.String("*"))
// Use S3 managed server side encryption (default)
encryptedBucketDefault := awscdkawss3tablesalpha.NewTableBucket(*scope, jsii.String("EncryptedTableBucketDefault"), &TableBucketProps{
TableBucketName: jsii.String("table-bucket-3"),
Encryption: *awscdkawss3tablesalpha.TableBucketEncryption_S3_MANAGED,
})
When using KMS encryption (TableBucketEncryption.KMS), if no encryption key is provided, CDK will automatically create a new KMS key for the table bucket with necessary permissions.
ts
// If no key is provided, one will be created automatically
const encryptedBucketAuto = new TableBucket(scope, 'EncryptedTableBucketAuto', {
tableBucketName: 'table-bucket-2',
encryption: TableBucketEncryption.KMS,
});
python
# If no key is provided, one will be created automatically
encrypted_bucket_auto = TableBucket(scope, "EncryptedTableBucketAuto",
table_bucket_name="table-bucket-2",
encryption=TableBucketEncryption.KMS
)
java
// If no key is provided, one will be created automatically
TableBucket encryptedBucketAuto = TableBucket.Builder.create(scope, "EncryptedTableBucketAuto")
.tableBucketName("table-bucket-2")
.encryption(TableBucketEncryption.KMS)
.build();
csharp
// If no key is provided, one will be created automatically
var encryptedBucketAuto = new TableBucket(scope, "EncryptedTableBucketAuto", new TableBucketProps {
TableBucketName = "table-bucket-2",
Encryption = TableBucketEncryption.KMS
});
go
// If no key is provided, one will be created automatically
encryptedBucketAuto := awscdkawss3tablesalpha.NewTableBucket(*scope, jsii.String("EncryptedTableBucketAuto"), &TableBucketProps{
TableBucketName: jsii.String("table-bucket-2"),
Encryption: *awscdkawss3tablesalpha.TableBucketEncryption_KMS,
})
Enabling CloudWatch Request Metrics
You can enable CloudWatch request metrics for your table bucket. Request metrics provide insight into Amazon S3 Tables requests, helping you monitor and optimize your table bucket usage.
For more information about S3 Tables CloudWatch metrics, see the S3 Tables CloudWatch Metrics documentation.
ts
// Enable CloudWatch request metrics for the table bucket
const tableBucketWithMetrics = new TableBucket(scope, 'TableBucketWithMetrics', {
tableBucketName: 'metrics-enabled-bucket',
requestMetricsStatus: RequestMetricsStatus.ENABLED,
});
python
# Enable CloudWatch request metrics for the table bucket
table_bucket_with_metrics = TableBucket(scope, "TableBucketWithMetrics",
table_bucket_name="metrics-enabled-bucket",
request_metrics_status=RequestMetricsStatus.ENABLED
)
java
// Enable CloudWatch request metrics for the table bucket
TableBucket tableBucketWithMetrics = TableBucket.Builder.create(scope, "TableBucketWithMetrics")
.tableBucketName("metrics-enabled-bucket")
.requestMetricsStatus(RequestMetricsStatus.ENABLED)
.build();
csharp
// Enable CloudWatch request metrics for the table bucket
var tableBucketWithMetrics = new TableBucket(scope, "TableBucketWithMetrics", new TableBucketProps {
TableBucketName = "metrics-enabled-bucket",
RequestMetricsStatus = RequestMetricsStatus.ENABLED
});
go
// Enable CloudWatch request metrics for the table bucket
tableBucketWithMetrics := awscdkawss3tablesalpha.NewTableBucket(*scope, jsii.String("TableBucketWithMetrics"), &TableBucketProps{
TableBucketName: jsii.String("metrics-enabled-bucket"),
RequestMetricsStatus: *awscdkawss3tablesalpha.RequestMetricsStatus_ENABLED,
})
Configuring Storage Class
You can configure the storage class for your table bucket and tables. Storage class determines how data is stored and billed, allowing you to optimize for different access patterns.
ts
// Create a table bucket with INTELLIGENT_TIERING storage class
const tableBucketWithStorageClass = new TableBucket(scope, 'TableBucketWithStorageClass', {
tableBucketName: 'storage-class-bucket',
storageClass: StorageClass.INTELLIGENT_TIERING,
});
python
# Create a table bucket with INTELLIGENT_TIERING storage class
table_bucket_with_storage_class = TableBucket(scope, "TableBucketWithStorageClass",
table_bucket_name="storage-class-bucket",
storage_class=StorageClass.INTELLIGENT_TIERING
)
java
// Create a table bucket with INTELLIGENT_TIERING storage class
TableBucket tableBucketWithStorageClass = TableBucket.Builder.create(scope, "TableBucketWithStorageClass")
.tableBucketName("storage-class-bucket")
.storageClass(StorageClass.INTELLIGENT_TIERING)
.build();
csharp
// Create a table bucket with INTELLIGENT_TIERING storage class
var tableBucketWithStorageClass = new TableBucket(scope, "TableBucketWithStorageClass", new TableBucketProps {
TableBucketName = "storage-class-bucket",
StorageClass = StorageClass.INTELLIGENT_TIERING
});
go
// Create a table bucket with INTELLIGENT_TIERING storage class
tableBucketWithStorageClass := awscdkawss3tablesalpha.NewTableBucket(*scope, jsii.String("TableBucketWithStorageClass"), &TableBucketProps{
TableBucketName: jsii.String("storage-class-bucket"),
StorageClass: *awscdkawss3tablesalpha.StorageClass_INTELLIGENT_TIERING,
})
Tables inherit the storage class from their parent bucket by default. You can also override the storage class at the table level:
ts
// Create a table with explicit storage class (overrides bucket default)
const tableWithStorageClass = new Table(scope, 'TableWithStorageClass', {
tableName: 'storage_class_table',
namespace: namespace,
openTableFormat: OpenTableFormat.ICEBERG,
withoutMetadata: true,
storageClass: StorageClass.STANDARD,
});
python
# Create a table with explicit storage class (overrides bucket default)
table_with_storage_class = Table(scope, "TableWithStorageClass",
table_name="storage_class_table",
namespace=namespace,
open_table_format=OpenTableFormat.ICEBERG,
without_metadata=True,
storage_class=StorageClass.STANDARD
)
java
// Create a table with explicit storage class (overrides bucket default)
Table tableWithStorageClass = Table.Builder.create(scope, "TableWithStorageClass")
.tableName("storage_class_table")
.namespace(namespace)
.openTableFormat(OpenTableFormat.ICEBERG)
.withoutMetadata(true)
.storageClass(StorageClass.STANDARD)
.build();
csharp
// Create a table with explicit storage class (overrides bucket default)
var tableWithStorageClass = new Table(scope, "TableWithStorageClass", new TableProps {
TableName = "storage_class_table",
Namespace = namespace,
OpenTableFormat = OpenTableFormat.ICEBERG,
WithoutMetadata = true,
StorageClass = StorageClass.STANDARD
});
go
// Create a table with explicit storage class (overrides bucket default)
tableWithStorageClass := awscdkawss3tablesalpha.NewTable(*scope, jsii.String("TableWithStorageClass"), &TableProps{
TableName: jsii.String("storage_class_table"),
Namespace: namespace,
OpenTableFormat: *awscdkawss3tablesalpha.OpenTableFormat_ICEBERG,
WithoutMetadata: jsii.Boolean(true),
StorageClass: *awscdkawss3tablesalpha.StorageClass_STANDARD,
})
Available storage classes:
StorageClass.STANDARD- For frequently accessed dataStorageClass.INTELLIGENT_TIERING- Automatically moves data between access tiers based on usage patterns
Note: Table storage class is a create-only property and cannot be changed after the table is created.
Controlling Table Permissions
ts
// Grant the principal read permissions to the table
const accountId = '123456789012'
table.grantRead(new iam.AccountPrincipal(accountId));
// Grant the role write permissions to the table
const role = new iam.Role(stack, 'MyRole', { assumedBy: new iam.ServicePrincipal('sample') });
table.grantWrite(role);
// Grant the user read and write permissions to the table
table.grantReadWrite(new iam.User(stack, 'MyUser'));
// Grant an account permissions to the table
table.grantReadWrite(new iam.AccountPrincipal(accountId));
// Add custom resource policy statements
const permissions = new iam.PolicyStatement({
effect: iam.Effect.ALLOW,
actions: ['s3tables:*'],
principals: [ new iam.ServicePrincipal('example.aws.internal') ],
resources: ['*']
});
table.addToResourcePolicy(permissions);
python
# Grant the principal read permissions to the table
account_id = "123456789012"
table.grant_read(iam.AccountPrincipal(account_id))
# Grant the role write permissions to the table
role = iam.Role(stack, "MyRole", assumed_by=iam.ServicePrincipal("sample"))
table.grant_write(role)
# Grant the user read and write permissions to the table
table.grant_read_write(iam.User(stack, "MyUser"))
# Grant an account permissions to the table
table.grant_read_write(iam.AccountPrincipal(account_id))
# Add custom resource policy statements
permissions = iam.PolicyStatement(
effect=iam.Effect.ALLOW,
actions=["s3tables:*"],
principals=[iam.ServicePrincipal("example.aws.internal")],
resources=["*"]
)
table.add_to_resource_policy(permissions)
java
// Grant the principal read permissions to the table
String accountId = "123456789012";
table.grantRead(new AccountPrincipal(accountId));
// Grant the role write permissions to the table
Role role = Role.Builder.create(stack, "MyRole").assumedBy(new ServicePrincipal("sample")).build();
table.grantWrite(role);
// Grant the user read and write permissions to the table
table.grantReadWrite(new User(stack, "MyUser"));
// Grant an account permissions to the table
table.grantReadWrite(new AccountPrincipal(accountId));
// Add custom resource policy statements
PolicyStatement permissions = PolicyStatement.Builder.create()
.effect(Effect.ALLOW)
.actions(List.of("s3tables:*"))
.principals(List.of(new ServicePrincipal("example.aws.internal")))
.resources(List.of("*"))
.build();
table.addToResourcePolicy(permissions);
csharp
// Grant the principal read permissions to the table
var accountId = "123456789012";
table.GrantRead(new AccountPrincipal(accountId));
// Grant the role write permissions to the table
var role = new Role(stack, "MyRole", new RoleProps { AssumedBy = new ServicePrincipal("sample") });
table.GrantWrite(role);
// Grant the user read and write permissions to the table
table.GrantReadWrite(new User(stack, "MyUser"));
// Grant an account permissions to the table
table.GrantReadWrite(new AccountPrincipal(accountId));
// Add custom resource policy statements
var permissions = new PolicyStatement(new PolicyStatementProps {
Effect = Effect.ALLOW,
Actions = new [] { "s3tables:*" },
Principals = new [] { new ServicePrincipal("example.aws.internal") },
Resources = new [] { "*" }
});
table.AddToResourcePolicy(permissions);
go
// Grant the principal read permissions to the table
accountId := "123456789012"
table.grantRead(iam.NewAccountPrincipal(accountId))
// Grant the role write permissions to the table
role := iam.NewRole(stack, jsii.String("MyRole"), &RoleProps{
AssumedBy: iam.NewServicePrincipal(jsii.String("sample")),
})
table.grantWrite(role)
// Grant the user read and write permissions to the table
table.grantReadWrite(iam.NewUser(stack, jsii.String("MyUser")))
// Grant an account permissions to the table
table.grantReadWrite(iam.NewAccountPrincipal(accountId))
// Add custom resource policy statements
permissions := iam.NewPolicyStatement(&PolicyStatementProps{
Effect: iam.Effect_ALLOW,
Actions: []*string{
jsii.String("s3tables:*"),
},
Principals: []IPrincipal{
iam.NewServicePrincipal(jsii.String("example.aws.internal")),
},
Resources: []*string{
jsii.String("*"),
},
})
table.addToResourcePolicy(permissions)
Tagging
Both TableBucket and Table support tagging through CDK's standard tagging mechanism:
ts
Tags.of(tableBucket).add('Environment', 'Production');
Tags.of(table).add('Team', 'DataEngineering');
// Stack-level tags propagate to all resources
Tags.of(stack).add('Project', 'DataLake');
python
Tags.of(table_bucket).add("Environment", "Production")
Tags.of(table).add("Team", "DataEngineering")
# Stack-level tags propagate to all resources
Tags.of(stack).add("Project", "DataLake")
java
Tags.of(tableBucket).add("Environment", "Production");
Tags.of(table).add("Team", "DataEngineering");
// Stack-level tags propagate to all resources
Tags.of(stack).add("Project", "DataLake");
csharp
Tags.Of(tableBucket).Add("Environment", "Production");
Tags.Of(table).Add("Team", "DataEngineering");
// Stack-level tags propagate to all resources
Tags.Of(stack).Add("Project", "DataLake");
go
awscdk.Tags_Of(tableBucket).Add(jsii.String("Environment"), jsii.String("Production"))
awscdk.Tags_Of(table).Add(jsii.String("Team"), jsii.String("DataEngineering"))
// Stack-level tags propagate to all resources
awscdk.Tags_Of(stack).Add(jsii.String("Project"), jsii.String("DataLake"))
Types
| Name | Kind | Summary |
|---|---|---|
Namespace | Construct (L2) | An S3 Tables Namespace with helpers. |
Table | Construct (L2) | An S3 Table with helpers. |
TableBucket | Construct (L2) | An S3 table bucket with helpers for associated resource policies. |
TableBucketPolicy | Construct (L2) | A Bucket Policy for S3 TableBuckets. |
TablePolicy | Construct (L2) | A Policy for S3 Tables. |
CompactionProperty | Struct | Settings governing the Compaction maintenance action. |
IcebergMetadataProperty | Struct | Contains details about the metadata for an Iceberg table. |
IcebergPartitionField | Struct | Partition field definition for Iceberg table. |
IcebergPartitionSpec | Struct | Partition specification for Iceberg table. |
IcebergSchemaProperty | Struct | Contains details about the schema for an Iceberg table. |
IcebergSortField | Struct | Sort field definition for Iceberg table. |
IcebergSortOrder | Struct | Sort order specification for Iceberg table. |
IcebergTransform | Class | Iceberg transform values for partition and sort fields. |
INamespace | Interface | Represents an S3 Tables Namespace. |
ITable | Interface | Represents an S3 Table. |
ITableBucket | Interface | Interface definition for S3 Table Buckets. |
NamespaceAttributes | Struct | Attributes for importing an existing namespace. |
NamespaceProps | Struct | Parameters for constructing a Namespace. |
NullOrder | Enum | Null ordering values for Iceberg sort fields. |
OpenTableFormat | Enum | Supported open table formats. |
RequestMetricsStatus | Enum | Controls whether CloudWatch request metrics are enabled or disabled for the table bucket. |
SchemaFieldProperty | Struct | Contains details about a schema field. |
SnapshotManagementProperty | Struct | Contains details about the snapshot management settings for an Iceberg table. |
SortDirection | Enum | Sort direction values for Iceberg sort fields. |
Status | Enum | Status values for maintenance actions. |
StorageClass | Enum | Storage class for S3 Tables. |
TableAttributes | Struct | A reference to a table outside this stack. |
TableBucketAttributes | Struct | A reference to a table bucket outside this stack. |
TableBucketEncryption | Enum | Controls Server Side Encryption (SSE) for this TableBucket. |
TableBucketPolicyProps | Struct | Parameters for constructing a TableBucketPolicy. |
TableBucketProps | Struct | Parameters for constructing a TableBucket. |
TablePolicyProps | Struct | Parameters for constructing a TablePolicy. |
TablePropertyEntry | Struct | A single table property key-value pair for Iceberg table configuration. |
TableProps | Struct | Properties for creating a new S3 Table. |
UnreferencedFileRemoval | Struct | Unreferenced file removal settings for the this table bucket. |
UnreferencedFileRemovalStatus | Enum | Controls whether unreferenced file removal is enabled or disabled. |