Serverless Spark支持通过自动或手动解冻OSS归档文件，确保SQL作业连续执行，需版本esr-4.4.0及以上。

当Spark作业需读取OSS归档存储中的数据时，因文件处于冻结状态无法直接访问，导致任务失败。本功能支持自动或手动触发解冻流程，确保作业正常执行，提升冷数据处理效率。

使用限制

仅Serverless Spark以下引擎版本支持本文操作：

esr-4.x：esr-4.4.0及之后版本。
esr-3.x：esr-3.4.0及之后版本。
esr-2.x：esr-2.8.0及之后版本。

工作原理

OSS归档存储（Archive Storage）中的对象默认不可读，必须先提交解冻请求并等待其进入可读状态。Serverless Spark通过SQL解析阶段识别待读取的OSS归档文件，并依据配置决定是否自动发起解冻请求。

自动模式：在生成执行计划（plan）阶段扫描所有涉及的归档文件，向OSS提交解冻请求，默认阻塞等待解冻完成。
同步/异步模式（detach）：提交解冻请求后不等待完成，继续执行后续操作。
手动模式：显式使用 RESTORE TABLE SQL语法提前解冻指定表或分区。

自动解冻

配置Spark参数以启用并控制OSS归档文件的自动解冻行为。适用于不确定具体解冻范围但需处理大量历史冷数据的ETL作业。

自动解冻配置

参数	类型	默认值	说明
`spark.sql.emr.autoRestoreOssArchive.enabled`	boolean	false	总开关，true时启用自动解冻。
`spark.sql.emr.autoRestoreOssArchive.detach`	boolean	false	true时异步解冻（不等待完成）。
`spark.sql.emr.autoRestoreOssArchive.tier`	string	-	解冻消耗优先级。 Expedited：高优先级，表示1小时内完成解冻。 Standard：标准，表示2~5小时内完成解冻。 Bulk：批量，表示5~12小时内完成解冻。更多，请参见解冻消耗时间。
`spark.sql.emr.autoRestoreOssArchive.limitSize`	string	1G	单表解冻大小上限。
`spark.sql.emr.autoRestoreOssArchive.days`	int	1	解冻状态持续天数。更多，请参见解冻状态持续时间。
`spark.sql.emr.autoRestoreOssArchive.loopIntervalInSecond`	int	5	轮询间隔（秒）。
`spark.sql.emr.autoRestoreOssArchive.log.level`	string	DEBUG	解冻过程日志级别。 DEBUG：详细的操作信息，适合排查问题。 INFO：常规操作记录，如请求成功或失败。 WARNING：潜在问题的警告信息。 ERROR：错误信息，表示操作失败。 CRITICAL：严重错误信息。

自动解冻示例

启用自动解冻功能

--conf spark.sql.emr.autoRestoreOssArchive.enabled=true

（可选）选择同步/异步模式
- 同步模式：detach=false（默认），确保所有文件就绪后再执行Job，适用于高可靠性的生产任务。
- 异步模式：detach=true，快速启动作业，后续重试补漏。
- 混合使用：建议采用 detach 模式首先触发解冻操作，然后再进行实际计算。例如，在 SQL 中涉及分区列的计算求值场景。
  - 提交预解冻作业（异步模式）：首先提交一个 Spark 作业，开启 detach 模式，该作业会在访问每个表时提交解冻请求，但不等待解冻完成。
  - 提交实际计算作业（同步模式）：待预解冻作业提交后失败，再次提交一个 Spark 作业，关闭 detach 模式，使作业同步等待所有文件解冻完成。

（可选）设置解冻层级与时长：平衡成本与速度。

--conf spark.sql.emr.autoRestoreOssArchive.tier=Standard    
--conf spark.sql.emr.autoRestoreOssArchive.days=1

（可选）调整轮询间隔与日志级别。

--conf spark.sql.emr.autoRestoreOssArchive.loopIntervalInSecond=10
--conf spark.sql.emr.autoRestoreOssArchive.log.level=WARN

提交Spark作业：完成配置后正常提交SQL或Spark应用，系统将在Plan阶段自动触发解冻流程。

spark-sql \
  --conf spark.sql.emr.autoRestoreOssArchive.enabled=true \
  --conf spark.sql.emr.autoRestoreOssArchive.detach=false \
  -e "SELECT count(*) FROM archived_table"

手动解冻

通过显式SQL命令对特定表或分区执行解冻操作，适用于已知明确解冻范围、需提前准备数据的场景。

全表解冻

解冻整个表对应的OSS归档文件供后续查询。

RESTORE TABLE table_name;

指定分区解冻

精细化控制解冻粒度，节省资源与时间。

RESTORE TABLE table_name PARTITION (pt1='a', pt2='b');

自定义解冻参数

临时修改全局配置，满足特殊需求。

RESTORE TABLE table_name PARTITION (dt='2024-01-01') OPTIONS ('days'='7', 'tier'='Standard');

支持的OPTIONS。

SQL Option	对应Conf参数
`'days'='7'`	`spark.sql.emr.autoRestoreOssArchive.days`
`'tier'='EXPEDITED'`	`spark.sql.emr.autoRestoreOssArchive.tier`
`'limitSize'='5G'`	`spark.sql.emr.autoRestoreOssArchive.limitSize`
`'detach'='true'`	`spark.sql.emr.autoRestoreOssArchive.detach`

说明

SQL中 OPTIONS优先级高于Spark Conf配置。

预览待解冻文件列表

支持通过EXPLAIN语法，查看待解冻文件列表，但不执行实际解冻操作。

EXPLAIN RESTORE TABLE table_name PARTITION (pt1='a', pt2='b') OPTIONS ('days'='1');

应用于生产环境

推荐手动预解冻：对于定时调度的关键报表任务，建议在作业前通过 RESTORE TABLE 主动解冻所需分区，减少运行时延迟。
合理设置 tier 和 days：
- Expedited 成本较高，仅用于紧急恢复，非紧急任务优先使用 Standard 。
- 合理设置 days，避免长时间保留。
资源配额预留：大规模解冻可能引发OSS API限流，建议错峰执行或联系技术支持提升配额。

计费说明

启用解冻功能本身不产生额外费用，但会间接触发以下计费项：

计费项	说明
数据取回费用	根据解冻的数据量收取数据取回费用，具体费用与解冻优先级和存储类型相关。
临时存储费用	解冻期间文件占用标准存储空间，按小时计费。
请求次数费用	每次解冻操作会根据请求次数收取费用。

具体收费规则，请参见OSS解冻文件计费说明。

常见问题

Q1：解冻是并发还是串行？

A：多个Scan之间的解冻请求为串行提交，但OSS服务端内部处理为异步并发。整体性能受OSS限速影响。

Q2：如何选择自动解冻 vs 手动解冻？

手动解冻适用：已知固定分区范围、可提前准备数据的场景（如每日T+1报表）。
自动解冻适用：动态SQL、多层JOIN后才确定读取路径的复杂作业。

Q3：为什么设置了 detach=true 导致作业失败？

A：虽然不等待解冻完成，但在Task真正读取文件时仍需文件处于“解冻中”或“已解冻”状态。若此时文件尚未开始解冻或超时未完成，I/O将失败。

Q4：EXPLAIN RESTORE 显示路径为空？

A：请确认表的Location路径确实指向OSS上的归档文件，并且元数据中正确标识了存储类型。可通过 DESC FORMATTED table_name 查看详细信息。