ARCHIVE TABLE
功能概述
ARCHIVE TABLE
ARCHIVE TABLE
用于将分区表指定分区的数据文件转换为对象存储的
STANDARD
STANDARD
、
IA
IA
或
ARCHIVE
ARCHIVE
类型，并写入该表的 Table Volume。该命令适合需要降低低频数据存储成本的场景；归档不会删除原表中的数据，也不依赖
data_retention_days
data_retention_days
。
语法
ARCHIVE TABLE [<namespace>.]<table_name>
PARTITION (<partition_key> = <partition_value>)
SUBDIRECTORY '<path>'
STORAGE_CLASS = '<storage_class>';
参数说明
| 参数 | 说明 |
|---|
<namespace>
<namespace> | 可选。表所属的 schema 名称。省略时使用当前 schema。 |
<table_name>
<table_name> | 要归档的分区表名称。仅支持分区表。 |
PARTITION
PARTITION | 指定要归档的分区，分区键必须属于目标表；当前一次命令只能指定一个分区。 |
SUBDIRECTORY '<path>'
SUBDIRECTORY '<path>' | 指定归档文件在目标表 Table Volume 下的子目录。建议按用途和日期建立独立目录，例如 archive/20260825/
archive/20260825/ 。 |
STORAGE_CLASS
STORAGE_CLASS | 指定对象存储类型，可选 STANDARD
STANDARD 、IA
IA 或 ARCHIVE
ARCHIVE ，不区分大小写。IA
IA 文件可直接读取；ARCHIVE
ARCHIVE 文件读取前必须执行 RESTORE TABLE
RESTORE TABLE 。 |
⚠️ 注意：同一分区不能重复归档。需要重新归档时，应先清理已有归档文件。
使用示例
示例 1：准备分区表和测试数据
CREATE TABLE public.doc_archive_orders (
order_id BIGINT,
amount DECIMAL(18,2)
) PARTITIONED BY (dt STRING);
INSERT INTO public.doc_archive_orders PARTITION (dt = '2026-08-28')
VALUES (1, 12.34), (2, 56.78);
INSERT INTO public.doc_archive_orders PARTITION (dt = '2026-08-29')
VALUES (3, 90.12);
上述建表和写入语句执行成功后，表包含
2026-08-28
2026-08-28
和
2026-08-29
2026-08-29
两个分区。
示例 2：将分区归档为 IA
ARCHIVE TABLE public.doc_archive_orders
PARTITION (dt = '2026-08-28')
SUBDIRECTORY 'ia/20260828/'
STORAGE_CLASS = 'IA';
命令同步执行。执行成功后，归档文件位于表的 Table Volume 中，
IA
IA
文件可以直接读取。
示例 3：将分区归档为 ARCHIVE
ARCHIVE TABLE public.doc_archive_orders
PARTITION (dt = '2026-08-29')
SUBDIRECTORY 'archive/20260829/'
STORAGE_CLASS = 'ARCHIVE';
命令同步执行。执行成功后，归档文件位于表的 Table Volume 中；读取该分区前，需要先执行 RESTORE TABLE（归档文件取回）。
示例 4：查看归档文件
SHOW TABLE VOLUME DIRECTORY public.doc_archive_orders;
示例返回的文件清单如下：
| relative_path | size |
|---|
archive/20260829/part00001
archive/20260829/part00001 | 1832 |
ia/20260828/part00001
ia/20260828/part00001 | 1850 |
relative_path
relative_path
是相对于该表 Table Volume 的路径。归档命令返回的 job id、分区键和值、归档时间和文件清单建议一并记录，便于后续校验和恢复。
注意事项
- 仅支持分区表，且一次命令只能指定一个分区。
- 单次归档的分区文件数不能超过 10000 个；文件数过多时应先缩小范围或执行 compaction。
- 归档操作是同步命令，成功返回表示指定分区的归档已完成。
- 归档不会删除原表中的数据；如需释放原表数据空间，应另行删除分区或配置生命周期策略。
IA
IA
文件可以直接读取，并产生相应的读取请求和流量费用。ARCHIVE
ARCHIVE
文件不能直接读取，必须先使用 RESTORE TABLE
RESTORE TABLE
取回，并产生取回费用和临时标准存储费用。- 执行用户需要对目标表具有
SELECT
SELECT
权限。
相关文档
