# @aws-cdk/aws-s3tables-alpha 中文文档 规范地址：https://npmcn.com/package/%40aws-cdk/aws-s3tables-alpha/ 版本：2\.275\.0-alpha\.0 npm 元数据更新时间：2026-10-26T19:19:49.829Z 中文译文更新时间：2026-11-07T14:12:07.138Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40aws-cdk/aws-s3tables-alpha 原文对照：https://npmcn.com/package/%40aws-cdk/aws-s3tables-alpha/?lang=original 项目主页：https://github.com/aws/aws-cdk 源码仓库：https://github.com/aws/aws-cdk ## 关键信息（来自 npm 元数据） - 包体积（解压后）：739 kB，27 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - Node.js 要求：\>= 20\.0\.0 - 运行依赖：0 个 - peer 依赖：constructs ^10\.5\.0，aws-cdk-lib ^2\.275\.0 - 首次发布：2025-04-17T03:45:52.605Z - 最新版本发布：2026-10-26T19:19:48.315Z - 近 30 天下载量：28295（2026-10-08 至 2026-11-06，npm 官方下载统计） - 已发布版本数：104（近 12 个月 64 个） ## 中文简介 S3 表格的 CDK 构造 ## 安装 ```sh npm install @aws-cdk/aws-s3tables-alpha ``` 也可以使用：`pnpm add @aws-cdk/aws-s3tables-alpha`、`yarn add @aws-cdk/aws-s3tables-alpha`、`bun add @aws-cdk/aws-s3tables-alpha` ## README # 亚马逊 S3 表格构造库 * * * ![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge) > 本单元中更高层次的构件的API是实验性的并正在积极开发中. 在今后任何版本中,它们都须作非背向相容的修改或去除。 这些是 不适用 [语义版本](https://semver.org/) 模型和断开的更改 在发行笔记中宣布. 这意味着虽然你可能使用它们,但可能需要更新 当更新到此软件包的更新版本时,您的源代码. * * * ## 亚马逊 S3 表 Amazon S3 Tables提供首个有内置Apache Iceberg支持的云对象商店,并精简了规模存储表格数据. [产品页](https://aws.amazon.com/s3/features/tables/) | [用户指南](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables.html) ## 使用量 ### 定义 S3 表格盒 ```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, } }); ``` 何时 `tableBucketName` 中省略,CDK从堆栈名称和 构建路径。 由于路径是输入的一部分,生成的名称是 **没有 横跨堆栈或构造重命名** - 重命名或移动构造 生成不同的名称并替换桶。 如果你需要一个固定的,可预测的 名称( 例如, 引用来自 CDK 外部或隔开的桶) 部署),通过 `tableBucketName` 当然. ### 定义 S3 表格命名空间 ```ts // Build a namespace const sampleNamespace = new Namespace(scope, 'ExampleNamespace', { namespaceName: 'example-namespace-1', tableBucket: tableBucket, }); ``` ### 定义 S3 表格 ```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, }, }); ``` 更多关于表格桶维护操作和默认行为的信息 [S3 表格用户指南](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-table-buckets-maintenance.html) ### 高级 Iceberg 表格配置 您可以配置分区规格、排序顺序和表格属性,以便优化查询性能. 将分区添加到表格的最简单方式 : ```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', }, ], }, }, }); ``` 对于全控,您也可以配置排序命令和表格属性 : ```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' }, ], }, }); ``` ### 控制表盘权限 ```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); ``` ### 控制表格密钥加密设置 S3 TableBuckets 默认使用 S3 管理的密钥启用 SSE (服务器侧加密 AES-256). 您也可以为 KMS- SSE 带来自己的 KMS 密钥, 或者让 S3 为您创建 KMS 密钥 . 如果一个被 KMS 加密的桶, 桶上的赠款功能也会允许访问 到 TableBucket 的相关 KMS 密钥. ```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 }); ``` 当使用 KMS 加密时( W)`TableBucketEncryption.KMS`),如果不提供加密密钥,CDK会自动为表格桶创建新的KMS密钥,并获得必要的权限. ```ts // If no key is provided, one will be created automatically const encryptedBucketAuto = new TableBucket(scope, 'EncryptedTableBucketAuto', { tableBucketName: 'table-bucket-2', encryption: TableBucketEncryption.KMS, }); ``` ### 启用云表请求量表 您可以启用 Cloud Watch 程序为您的餐桌桶请求参数 。 请求度量衡为亚马逊S3表格请求提供了洞察力,帮助您监控并优化了表格桶的使用. 有关S3表云观察测量的更多信息,请参见: [S3 表云观察度量衡文档](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-cloudwatch-metrics.html)。 。 。 . ```ts // Enable CloudWatch request metrics for the table bucket const tableBucketWithMetrics = new TableBucket(scope, 'TableBucketWithMetrics', { tableBucketName: 'metrics-enabled-bucket', requestMetricsStatus: RequestMetricsStatus.ENABLED, }); ``` ### 配置存储类 您可以为您的桌子桶和桌子配置存储类 。 存储类决定了数据的存储和计费方式,允许您优化不同的访问模式. ```ts // Create a table bucket with INTELLIGENT_TIERING storage class const tableBucketWithStorageClass = new TableBucket(scope, 'TableBucketWithStorageClass', { tableBucketName: 'storage-class-bucket', storageClass: StorageClass.INTELLIGENT_TIERING, }); ``` 表默认从母桶中继承存储类. 您也可以在表格级别上覆盖存储类 : ```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, }); ``` 可用的存储类 : - `StorageClass.STANDARD` - 经常获得的数据 - `StorageClass.INTELLIGENT_TIERING` - 根据使用模式,自动将数据移动到访问级别之间 注意:表存储类是只创建属性,在表创建后不能被更改. ### 控制表权限 ```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); ``` ### 缠绕 两者 `TableBucket` 财务报告和审定财务报表 `Table` 通过 CDK 标准标记机制支持标记 : ```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'); ``` ## 快来了 L2 构造支持 : - 表格的 KMS 加密支持 ## 常见问题 ### @aws-cdk/aws-s3tables-alpha 是什么？ S3 表格的 CDK 构造 ### 如何安装 @aws-cdk/aws-s3tables-alpha？ 在项目目录运行 npm install @aws-cdk/aws-s3tables-alpha，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：constructs（^10\.5\.0）、aws-cdk-lib（^2\.275\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @aws-cdk/aws-s3tables-alpha 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @aws-cdk/aws-s3tables-alpha 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @aws-cdk/aws-s3tables-alpha 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>= 20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @aws-cdk/aws-s3tables-alpha 可以商用吗？ @aws-cdk/aws-s3tables-alpha 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @aws-cdk/aws-s3tables-alpha 的下载量有多少？ 根据 npm 官方下载统计，@aws-cdk/aws-s3tables-alpha 在 2026/10/08 – 2026/11/06 这 30 天内被下载 28,295 次，日均约 943 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @aws-cdk/aws-s3tables-alpha 还在维护吗？ 最新版本 2\.275\.0-alpha\.0 发布于 2026/10/27（12 天前）；至今共发布 104 个版本，其中过去 12 个月发布了 64 个；首次发布于 2025/04/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。