# 快照保留优化
借助 Apache Iceberg 快照保留功能，用户可以查询特定时间点的历史数据并撤销对表的非预期修改。在 AWS Glue Data Catalog 中，快照保留配置功能会控制这些快照（表数据的不同版本）在过期和移除之前的保留期限。该功能会根据配置的保留期或要保留的最大快照数量自动移除较早的快照，有助于管理存储成本和元数据开销。
您可以为表配置保留期（以天为单位）和要保留的最大快照数量。AWS Glue 会从表元数据中移除早于指定保留期的快照，同时确保最新的快照数量保持在配置的限制范围内。从元数据中移除旧快照后，AWS Glue 会删除不再引用并且是已过期快照所独有的对应数据和元数据文件。这有利于确保仅需查询剩余保留的快照，同时回收已过期快照数据占用的存储空间。
**Topics**
+ [启用快照保留优化器](enable-snapshot-retention.md)
+ [更新快照保留优化器](update-snapshot-retention.md)
+ [禁用快照保留优化器](disable-snapshot-retention.md)
# 启用快照保留优化器
您可以在 Data Catalog 中使用 AWS Glue 控制台、AWS CLI 或 AWS API 为 Apache Iceberg 表启用快照保留优化器。对于新表，您可以在创建表时选择 Apache Iceberg 表格式并启用快照保留优化器。新表会默认禁用快照保留功能。
------
#### [ Console ]
**启用快照保留优化器**
1. 打开 AWS Glue 控制台（[https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)），然后以数据湖管理员、表创建者或已被授予表的 `glue:UpdateTable` 和 `lakeformation:GetDataAccess` 权限的用户身份登录。
1. 在导航窗格的**数据目录**下，请选择**表**。
1. 在**表**页面上，选择要为其启用快照保留优化器的 Iceberg 表，然后在**操作**菜单下，选择**优化**下的**启用**。
您也可以通过选中该表并打开**表详细信息**页面来启用优化。选择页面下半部的**表优化**选项卡，然后选择**启用快照保留**。
1. **启用优化**页面的**优化配置**下有两个选项：**使用默认设置**或**自定义设置**。如果您选择使用默认设置，则 AWS Glue 会使用 Iceberg 表配置中定义的属性来确定快照保留期和要保留的快照数量。如果没有此配置，AWS Glue 会将一个快照保留五天，并删除与过期快照关联的文件。
1. 然后选择 AWS Glue 可以代表您代入以运行优化器的 IAM 角色。有关 IAM 角色所需权限的详细信息，请参阅[表优化的先决条件](optimization-prerequisites.md)部分。
按照以下步骤更新一个现有的 IAM 角色：
1. 要更新 IAM 角色的权限策略，请在 IAM 控制台中转到用于运行压缩的 IAM 角色。
1. 在添加权限部分中，选择“创建策略”。在新打开的浏览器窗口中，创建将用于您的角色的新策略。
1. 在“创建策略”页面上，选择 JSON 选项卡。将“先决条件”中显示的 JSON 代码复制到策略编辑器字段中。
1. 如果您希望手动设置**快照保留配置**的值，请选择**自定义设置**。
![\[显示“启用保留 > 自定义设置”选项的 Apache Iceberg 表详细信息页面。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/table-enable-retention.png)
1. 选中**将选定的 IAM 角色应用于选定的优化器**选项，可将单个 IAM 角色用于所有已启用的优化器。
1. 如果您有安全策略配置，其中 Iceberg 表优化器需要从特定的虚拟私有云（VPC）访问 Amazon S3 存储桶，则请创建 AWS Glue 网络连接或使用现有网络连接。
如果您尚未设置 AWS Glue VPC 连接，则请使用 AWS Glue 控制台或 AWS CLI/SDK 按照[为连接器创建连接](https://docs.aws.amazon.com/glue/latest/dg/creating-connections.html)部分中的步骤创建一个新连接。
1. 然后在**快照保留配置**下，选择使用 [Iceberg 表配置](https://iceberg.apache.org/docs/1.5.2/configuration/#table-behavior-properties)中指定的值，或者为快照保留期（history.expire.max-snapshot-age-ms）和要保留的最小快照数量（history.expire.min-snapshots-to-keep）指定自定义值，以及连续快照删除作业运行之间的小时数。
1. 选择**删除关联文件**以在表优化器从表元数据中删除较早快照时删除底层文件。
如果未选中此选项，则在从表元数据中移除较早的快照时，其关联文件将作为孤立文件保留在存储中。
1. 阅读警告声明，然后选择**我确认**以继续操作。
**注意**
在 Data Catalog 中，快照保留优化器遵循由分支和标签级别保留策略控制的生命周期。有关更多信息，请参阅 Iceberg 文档中的 [Branching and tagging](https://iceberg.apache.org/docs/latest/branching/#overview) 部分。
1. 检查配置，然后选择**启用优化**。
等待几分钟，以便保留优化器运行并根据配置使较早的快照过期。
------
#### [ AWS CLI ]
要在 AWS Glue 中为新 Iceberg 表启用快照保留功能，需要创建一个 `retention` 类型的表优化器，并将 `table-optimizer-configuration` 中的 `enabled` 字段设置为 `true`。您可以使用 AWS CLI 命令 `create-table-optimizer` 或 `update-table-optimizer` 来完成此操作。此外，您需要根据自己的需求指定保留配置字段，例如 `snapshotRetentionPeriodInDays` 和 `numberOfSnapshotsToRetain`。
以下示例演示了启用快照保留优化器的方法。将账户 ID 替换为有效的 AWS 账户 ID。将数据库名称和表名称替换为实际的 Iceberg 表名称和数据库名称。将 `roleArn` 替换为具有运行快照保留优化器所需权限的 IAM 角色的 AWS 资源名称（ARN）和名称。
```
aws glue create-table-optimizer \
--catalog-id 123456789012 \
--database-name iceberg_db \
--table-name iceberg_table \
--table-optimizer-configuration '{"roleArn":"arn:aws:iam::123456789012:role/optimizer_role","enabled":'true', "vpcConfiguration":{
"glueConnectionName":"glue_connection_name"}, "retentionConfiguration":{"icebergConfiguration":{"snapshotRetentionPeriodInDays":7,"numberOfSnapshotsToRetain":3,"cleanExpiredFiles":'true'}}}'\
--type retention
```
此命令会为给定目录、数据库和区域中的指定 Iceberg 表创建保留优化器。table-optimizer-configuration 会指定要使用的 IAM 角色 ARN，启用该优化器并设置保留配置。在此示例中，它会将快照保留 7 天，至少保留 3 个快照，并清理已过期的文件。
+ snapshotRetentionPeriodInDays – 快照过期前将会保留的天数。默认值为 `5`。
+ numberOfSnapshotsToRetain – 要保留的最小快照数量，即使已超过保留期亦不例外。默认值为 `1`。
+ cleanExpiredFiles – 这是一个布尔值，指示是否在快照过期后删除已过期的数据文件。默认值为 `true`。
如果设置为 true，则会从表的元数据中移除较早的快照，并删除其底层文件。如果将此参数设置为 false，则会从表的元数据中移除较早的快照，但其底层文件仍作为孤立文件保留在存储中。
------
#### [ AWS API ]
调用 [CreateTableOptimizer](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-table-optimizers.html#aws-glue-api-table-optimizers-CreateTableOptimizer) 操作为表启用快照保留优化器。
------
启用压缩后，**表优化**选项卡会显示以下压缩详细信息（大约 15–20 分钟后）：
开始时间
快照保留优化器启动的时间。该值是一个采用 UTC 时间格式的时间戳。
运行时间
该时间指示优化器完成任务所花费的时间。该值是一个采用 UTC 时间格式的时间戳。
Status
优化器运行的状态。值为成功或失败。
已删除数据文件数
已删除的文件总数。
已删除清单文件数
已删除的清单文件总数。
已删除清单列表数
已删除的清单列表总数。
# 更新快照保留优化器
您可以使用 AWS Glue 控制台、AWS CLI 或 UpdateTableOptimizer API 更新特定 Apache Iceberg 表的现有快照保留优化器配置。
------
#### [ Console ]
**更新快照保留配置**
1. 登录 AWS 管理控制台，然后打开 AWS Glue 控制台，网址为：[https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)。
1. 选择**数据目录**，然后选择**表**。从表列表中，选择要更新快照保留优化器配置的 Iceberg 表。
1. 在**表详细信息**页面的下半部分，选择**表优化**选项卡，然后选择**编辑**。您还可以从该页面右上角的**操作**菜单中，选择**优化**下的**编辑**。
1. 然后在**编辑优化**页面上，进行所需的更改。
1. 选择**保存**。
------
#### [ AWS CLI ]
要使用 AWS CLI 更新快照保留优化器，您可以使用以下命令：
```
aws glue update-table-optimizer \
--catalog-id 123456789012 \
--database-name iceberg_db \
--table-name iceberg_table \
--table-optimizer-configuration '{"roleArn":"arn:aws:iam::123456789012:role/optimizer_role"","enabled":'true', "vpcConfiguration":{"glueConnectionName":"glue_connection_name"},"retentionConfiguration":{"icebergConfiguration":{"snapshotRetentionPeriodInDays":7,"numberOfSnapshotsToRetain":3,"cleanExpiredFiles":'true'}}}' \
--type retention
```
此命令会更新给定目录、数据库和区域中指定表的保留配置。关键参数如下：
+ snapshotRetentionPeriodInDays – 快照过期前将会保留的天数。默认值为 `1`。
+ numberOfSnapshotsToRetain – 要保留的最小快照数量，即使已超过保留期亦不例外。默认值为 `5`。
+ cleanExpiredFiles – 这是一个布尔值，指示是否在快照过期后删除已过期的数据文件。默认值为 `true`。
如果设置为 true，则会从表的元数据中移除较早的快照，并删除其底层文件。如果将此参数设置为 false，则会从表的元数据中移除较早的快照，但其底层文件仍作为孤立文件保留在存储中。
------
#### [ API ]
您可以使用 `UpdateTableOptimizer` API 来更新表优化器。您可以使用此 API 来更新有关压缩、保留或孤立文件删除功能的现有表优化器配置。请求参数包括：
+ catalogId（必填项）：包含该表的目录的 ID
+ databaseName（可选）：包含该表的数据库的名称
+ tableName（可选）：该表的名称
+ type（必填项）：表优化器的类型（压缩、保留或孤立文件删除）
+ retentionConfiguration（必填项）：更新后的表优化器配置，包括角色 ARN、启用状态、保留配置和孤立文件删除配置。
------
# 禁用快照保留优化器
您可以使用 AWS Glue 控制台或 AWS CLI 来为特定的 Apache Iceberg 表禁用快照保留优化器。
------
#### [ Console ]
**禁快照保留功能**
1. 登录 AWS 管理控制台，然后打开 AWS Glue 控制台，网址为：[https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)。
1. 选择**数据目录**，然后选择**表**。从表列表中，选择要禁用快照保留优化器的表。
1. 在**表详细信息**页面的下半部分，选择**表优化**和**禁用**，并选择**操作**下的**快照保留**。
您还可以从该页面右上角的**操作**菜单中，选择**优化**下的**禁用**。
1. 在确认消息页面选择**禁用**。您可以在以后重新启用快照保留优化器。
确认之后，快照保留优化器将被禁用，并且快照保留的状态将恢复为 `Not enabled`。
------
#### [ AWS CLI ]
将以下示例中的账户 ID 替换为有效的 AWS 账户 ID。将数据库名称和表名称替换为实际的 Iceberg 表名称和数据库名称。将 `roleArn` 替换为具有运行保留优化器所需权限的 IAM 角色的 AWS 资源名称（ARN）和实际名称。
```
aws glue update-table-optimizer \
--catalog-id 123456789012 \
--database-name iceberg_db \
--table-name iceberg_table \
--table-optimizer-configuration '{"roleArn":"arn:aws:iam::123456789012:role/optimizer_role", "vpcConfiguration":{"glueConnectionName":"glue_connection_name"}, "enabled":'false'}'\
--type retention
```
------
#### [ AWS API ]
调用 [UpdateTableOptimizer](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-table-optimizers.html#aws-glue-api-table-optimizers-UpdateTableOptimizer) 操作来为特定的表禁用快照保留优化器。
------