SQL Delta Lake 的 time travel AS OF 的历史版本查询模板

delta lake 的 time travel as of 功能支持按版本号或时间戳查询历史数据快照，需表为 delta 格式、logretentionduration 未过期且时间戳为 utc；可用 describe history 查看历史版本，dataframe api 中通过 option(“versionasof”) 或 option(“timestampasof”) 实现。

Delta Lake 的 TIME TRAVEL AS OF 功能允许你查询表在某个时间点或版本号时的数据快照，无需额外备份或导出。关键在于正确使用 VERSION AS OF 或 TIMESTAMP AS OF 语法，并确保表已启用 Delta Lake 格式（即底层是 `_delta_log` 目录结构）。

基础语法模板（spark sql）

以下是最常用、可直接复用的查询模板：

• 按版本号查询：select * FROM table_name VERSION AS OF 5;
• 按时间戳查询（ISO 8601 格式）：SELECT * FROM table_name TIMESTAMP AS OF '2024-03-15T10:30:00Z';
• 按相对时间查询（如 1 小时前）：SELECT * FROM table_name TIMESTAMP AS OF date_sub(current_timestamp(), 1);

使用前提与注意事项

不是所有表都支持 time travel，需确认以下几点：

• 表必须是 Delta 表（创建时用 using DELTA，或通过 CONVERT TO DELTA 转换）
• Delta 表的 logRetentionDuration 默认为 30 天，过期的 commit 日志会被清理，对应的历史版本将不可查
• 时间戳需为 UTC；若传入本地时区时间，可能查不到预期结果（建议显式加 Z 或使用 to_utc_timestamp() 转换）
• 版本号从 0 开始递增，每次成功写入（含 INSERT/UPDATE/delete/OPTIMIZE）都会生成新版本

查看历史版本信息（辅助定位）

不知道该查哪个版本或时间？先运行元数据查询：

• 列出所有可用版本及对应时间：DESCRIBE HISTORY table_name;
• 只看最近 5 次操作：DESCRIBE HISTORY table_name LIMIT 5;
• 过滤特定时间范围的操作：DESCRIBE HISTORY table_name WHERE timestamp > '2024-03-10';

在 DataFrame API 中使用（PySpark / Scala）

代码中也可通过 option 方式指定版本或时间：

• 按版本读取：spark.read.option("versionAsOf", "5").table("table_name")
• 按时间戳读取：spark.read.option("timestampAsOf", "2024-03-15T10:30:00Z").table("table_name")
• 注意：该 option 仅对 table() 或 load(path) 有效，不适用于直接 SQL 查询