Package software.amazon.awscdk.services.s3tables.alpha

@Stability(Experimental) package software.amazon.awscdk.services.s3tables.alpha

Amazon S3 Tables Construct Library

---

cdk-constructs: Experimental

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.

Product Page | User Guide

Usage

Define an S3 Table Bucket

 // Build a Table bucket
 TableBucket sampleTableBucket = TableBucket.Builder.create(scope, "ExampleTableBucket")
         .tableBucketName("example-bucket-1")
         // optional fields:
         .unreferencedFileRemoval(UnreferencedFileRemoval.builder()
                 .status(UnreferencedFileRemovalStatus.ENABLED)
                 .noncurrentDays(20)
                 .unreferencedDays(20)
                 .build())
         .build();

Define an S3 Tables Namespace

 // Build a namespace
 Namespace sampleNamespace = Namespace.Builder.create(scope, "ExampleNamespace")
         .namespaceName("example-namespace-1")
         .tableBucket(tableBucket)
         .build();

Define an S3 Table

 // 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();

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: 

 // 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();

For full control, you can also configure sort orders and table properties: 

 // 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();

Controlling Table Bucket Permissions

 // 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);

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. 

 // 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();

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. 

 // 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();

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. 

 // Enable CloudWatch request metrics for the table bucket
 TableBucket tableBucketWithMetrics = TableBucket.Builder.create(scope, "TableBucketWithMetrics")
         .tableBucketName("metrics-enabled-bucket")
         .requestMetricsStatus(RequestMetricsStatus.ENABLED)
         .build();

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. 

 // 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();

Tables inherit the storage class from their parent bucket by default. You can also override the storage class at the table level: 

 // 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();

Available storage classes:

  • StorageClass.STANDARD - For frequently accessed data
  • StorageClass.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

 // 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);

Tagging

Both TableBucket and Table support tagging through CDK's standard tagging mechanism: 

 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");

Coming Soon

L2 Construct support for:

  • KMS encryption support for Tables