Metadata-Version: 2.1
Name: aws-cdk.aws-s3tables-alpha
Version: 2.257.0a0
Summary: CDK Constructs for S3 Tables
Home-page: https://github.com/aws/aws-cdk
Author: Amazon Web Services
License: Apache-2.0
Project-URL: Source, https://github.com/aws/aws-cdk.git
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Typing :: Typed
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved
Classifier: Framework :: AWS CDK
Classifier: Framework :: AWS CDK :: 2
Requires-Python: ~=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: aws-cdk-lib<3.0.0,>=2.257.0
Requires-Dist: constructs<11.0.0,>=10.5.0
Requires-Dist: jsii<2.0.0,>=1.130.0
Requires-Dist: publication>=0.0.3
Requires-Dist: typeguard==2.13.3

# Amazon S3 Tables Construct Library

<!--BEGIN STABILITY BANNER-->---


![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)

> 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](https://semver.org/) 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.

---
<!--END STABILITY BANNER-->

## 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](https://aws.amazon.com/s3/features/tables/) | [User Guide](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables.html)

## Usage

### Define an S3 Table Bucket

```python
from aws_cdk.aws_s3tables_alpha import UnreferencedFileRemoval
# Build a Table bucket
sample_table_bucket = TableBucket(scope, "ExampleTableBucket",
    table_bucket_name="example-bucket-1",
    # optional fields:
    unreferenced_file_removal=UnreferencedFileRemoval(
        status=UnreferencedFileRemovalStatus.ENABLED,
        noncurrent_days=20,
        unreferenced_days=20
    )
)
```

### Define an S3 Tables Namespace

```python
# Build a namespace
sample_namespace = Namespace(scope, "ExampleNamespace",
    namespace_name="example-namespace-1",
    table_bucket=table_bucket
)
```

### Define an S3 Table

```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
    )
)
```

Learn more about table buckets maintenance operations and default behavior from the [S3 Tables User Guide](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-table-buckets-maintenance.html)

### 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:

```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"
            )
            ]
        )
    )
)
```

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

```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")
        ]
    )
)
```

### Controlling Table Bucket 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)
```

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

```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
)
```

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.

```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
)
```

### 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-cloudwatch-metrics.html).

```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
)
```

### Controlling Table 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)
```

### Tagging

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

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

## Coming Soon

L2 Construct support for:

* KMS encryption support for Tables
