本文介绍 Format Table 的特性,以及如何创建 Format Table、读写数据、管理分区和配置生命周期。
Format Table 简介
Format Table 用 Parquet、ORC、CSV、JSON 等标准文件格式存储数据,目录布局与 Hive 表兼容。Spark、Flink 等计算引擎通过 DLF Catalog 读写,其他程序也可以直接读写表目录下的文件。
您可以通过以下方式创建 Format Table:
-
通过 DLF 控制台创建,存储路径由 DLF 自动生成。
-
通过 SQL 创建的标准文件格式表(如 Spark SQL 的
USING Parquet或 Flink SQL 的type='format-table')。
Format Table 的主要特点
-
数据管理:元数据和数据文件都由 DLF 管理,存储路径按 UUID 自动生成,无需指定。
-
文件开放:数据文件采用标准格式,没有快照和清单文件;支持相应格式的工具可直接读取。
-
托管分区:启用后,分区由 DLF Catalog 登记和管理,支持分区 DDL、分区过期清理和存储分层。
-
删除保护:删除表后数据默认保留 1 天,期间可从回收站恢复。
选择 Format Table 还是 Paimon 表
|
需求 |
推荐表类型 |
|---|---|
|
流式写入,需要 exactly-once 和分区完成通知 |
Paimon 表 |
|
主键更新、时间旅行、增量读取 |
Paimon 表 |
|
批量加工的结果,下游按文件读取 |
Format Table |
|
与其他系统交换文件(程序写入、引擎读取,或反过来) |
Format Table |
|
从 Hive 迁移,保留原有文件格式和目录结构 |
Format Table |
使用限制
-
不支持主键、更新或删除单行数据,也不支持时间旅行和增量读取。
-
覆盖写不是原子操作;删除已有文件与写入新文件之间,查询可能读到空数据或部分数据。不要并发覆盖写同一分区。
-
没有后台小文件合并。文件数量由写入任务决定;Spark 写入前可按分区
repartition。 -
托管分区要求读写引擎支持该功能。旧版本引擎写入的分区须执行
MSCK REPAIR TABLE登记。
创建 Format Table
DLF控制台
登录数据湖构建控制台
-
在数据目录列表页面,单击Catalog名称,进入Catalog详情页。
-
在数据库列表中,单击数据库名称,进入表列表页。
-
在表列表中,单击新建数据表。
-
配置以下信息,单击确定。
配置项
说明
表格式
选择Format 表。
数据表名称
必填,数据库下不可重名。
数据表描述
可选,输入描述信息。
字段信息
定义列名称、数据类型、描述及是否为分区字段。Format Table 不支持主键。
表自定义属性
file.format:支持parquet、orc、csv、json,默认parquet。分区表添加metastore.partitioned-table=true开启托管分区。可添加自定义属性,在表创建过程中会覆盖DLF元数据服务对应的默认参数,适用的配置项详见Paimon官方文档。
SQL
以下示例创建开启托管分区的 Parquet Format Table。表路径由 DLF 自动生成。
-
Flink SQL
CREATE TABLE order_detail ( order_id BIGINT, amount DECIMAL(18, 2), dt STRING ) PARTITIONED BY (dt) WITH ( 'type'='format-table', 'file.format'='parquet', 'metastore.partitioned-table'='true' ); -
Spark SQL
CREATE TABLE order_detail ( order_id BIGINT, amount DECIMAL(18, 2), dt STRING ) USING parquet PARTITIONED BY (dt) TBLPROPERTIES ('metastore.partitioned-table' = 'true');
上述 SQL 示例显式设置了 metastore.partitioned-table=true,因此会开启托管分区。DLF 默认不会为 Format Table 开启托管分区。其他开启方式及默认行为,请参见开启托管分区。
建表时优先选择 Parquet 或 ORC;CSV 和 JSON 适合人工准备的小文件。分区字段使用 STRING 类型,取值与分区目录名一致,例如 dt=20261105。按小时分区可使用 dt、hour 两级。
查看 Format Table
-
在数据库列表中,单击数据库名称,可查看表列表。
-
在表列表中,单击表名称,可查看表字段。
-
单击表详情页签,可查看数据表基本信息、字段列表及分区定义。
-
单击权限页签,可为用户或角色授予数据表相关权限。详情请参见数据授权管理。
写入和读取数据
可通过 Spark、Flink、pypaimon、DataFusion 读写数据,也可通过控制台上传文件。对已开启托管分区的表,支持该功能的 Spark、Flink 和 DataFusion 写入后自动登记分区;pypaimon 和控制台上传文件后须手动登记。
计算引擎
-- 写入指定分区
INSERT INTO order_detail PARTITION (dt = '20261105')
SELECT order_id, amount FROM src;
-- 覆盖指定分区
INSERT OVERWRITE order_detail PARTITION (dt = '20261105')
SELECT order_id, amount FROM src;
SELECT * FROM order_detail WHERE dt = '20261105';
Spark 的 INSERT OVERWRITE 不带 PARTITION 子句时会覆盖整张表。本次未写到的分区的数据会被删除,分区登记仍保留。如只需覆盖本次写到的分区,先设置 spark.sql.sources.partitionOverwriteMode=dynamic。
Python SDK
pypaimon 可在 Python 程序中创建和读写 Format Table。向已开启托管分区的表写入后,调用 catalog.create_partitions() 登记分区。详细用法请参见通过 pypaimon 访问 Format Table。
控制台
-
在数据库的表列表中,单击目标 Format Table,在文件列表页签进入目标分区目录,例如
dt=20261105/。对于已开启托管分区的表,分区目录不存在时,先执行ADD PARTITION创建。 -
上传与表定义的文件格式、字段一致的文件。文件名不要以
.或_开头。 -
向已开启托管分区的表上传文件后,执行
ALTER TABLE ... ADD IF NOT EXISTS PARTITION或MSCK REPAIR TABLE登记分区,查询才能看到新数据。
分区管理
分区 Format Table 支持两种分区管理方式。默认情况下,DLF 从表目录发现分区;开启托管分区后,分区由 DLF Catalog 登记和管理,查询只返回已登记的分区。
开启托管分区
新建表开启托管分区
新建分区表时,可通过 DLF 控制台添加表属性 metastore.partitioned-table=true;通过 Spark SQL 创建时,在 TBLPROPERTIES 中设置该属性;通过 Flink SQL 创建时,在 WITH 中设置该属性。完整建表示例请参见创建 Format Table。
Catalog级别设置
建表时为当前表设置 metastore.partitioned-table=true。若希望某个 Catalog 下以后新建的分区 Format Table 默认开启托管分区,可在该 Catalog 设置 format-table-default.metastore.partitioned-table=true。当前表未设置该表属性、所属 Catalog 也未设置默认选项时,DLF 从表目录发现分区。
已有表开启托管分区
已有的表可以执行 ALTER TABLE t SET TBLPROPERTIES ('metastore.partitioned-table' = 'true') 开启托管分区。
已有的表开启托管分区后,必须先执行 MSCK REPAIR TABLE t 登记已有分区,否则查询结果为空。
托管分区与从目录发现分区的区别
|
对比项 |
托管分区(推荐) |
从目录发现分区(默认) |
|---|---|---|
|
查询返回的分区 |
已登记的分区。开启托管分区后,支持该功能的 Spark、Flink 通过 DLF Catalog 写入以及 DataFusion 写入时自动登记分区;pypaimon、控制台上传文件等方式写入后需要手动登记。 |
表目录下所有分区目录 |
|
分区过期清理、存储分层 |
支持 |
不支持 |
|
|
支持 |
不支持 |
|
分区很多时的查询规划 |
从 Catalog 列出分区 |
逐层列出 OSS 目录,分区越多越慢 |
登记和管理分区
本节 SQL 语句仅适用于开启托管分区的表。受支持的 Spark、Flink 通过 DLF Catalog 写入,或使用 DataFusion 写入时,分区会自动登记,无需手动登记。对于未自动登记的分区,知道分区值时执行 ADD PARTITION;需要扫描表目录时执行 MSCK REPAIR TABLE。通过 pypaimon 写入时,调用 catalog.create_partitions() 登记。
-
ALTER TABLE t ADD IF NOT EXISTS PARTITION (dt = '20261105'):登记分区;目录不存在时创建空目录。 -
ALTER TABLE t DROP PARTITION (dt = '20261105'):注销分区并删除目录下的数据。 -
MSCK REPAIR TABLE t:扫描并登记尚未登记的分区。添加DROP PARTITIONS可注销已不存在的分区;添加SYNC PARTITIONS同时执行两项操作。 -
SHOW PARTITIONS t:列出已登记的分区。 -
ANALYZE TABLE t PARTITION (dt = '20261105') COMPUTE STATISTICS NOSCAN:更新文件数、大小和最后写入时间;去掉NOSCAN可统计 Parquet、ORC 文件行数。
DROP PARTITION 会删除分区目录下的数据。
MSCK REPAIR TABLE 需要列出全表的分区目录,分区越多耗时越长。分区较多时,建议由写入方在写完后执行 ADD PARTITION。多级分区的 PARTITION 子句须从第一个分区字段开始指定。例如表按 (dt, hour) 分区时,可以指定 PARTITION (dt = '20261105'),不能只指定 PARTITION (hour = '08')。
分区过期清理和存储分层
开启托管分区的 Format Table 支持分区过期清理和存储分层,由 DLF 存储优化按分区执行,无需在 OSS 上配置生命周期规则。
未开启托管分区的分区表、使用纯值分区路径的表不支持生命周期管理。非分区表不支持分区过期,可在表级别修改存储类型。
分区过期清理
分区到期后,分区目录下的数据被删除,分区被注销。通过以下表属性配置:
-
partition.expiration-time:保留时间;不配置则永久保留。 -
partition.expiration-strategy:values-time(默认)按分区值中的日期计算;update-time按最后更新时间计算。 -
partition.timestamp-formatter:分区值的日期格式。 -
partition.timestamp-pattern:用于拼出日期的分区字段,默认取第一个分区字段。
按天分区、保留 30 天:
ALTER TABLE order_detail SET TBLPROPERTIES (
'partition.expiration-time' = '30 d',
'partition.timestamp-formatter' = 'yyyyMMdd'
);
按小时分区、保留 7 天:
ALTER TABLE order_detail_hourly SET TBLPROPERTIES (
'partition.expiration-time' = '7 d',
'partition.timestamp-pattern' = '$dt $hour:00:00',
'partition.timestamp-formatter' = 'yyyyMMdd HH:mm:ss'
);
存储分层
访问较少的分区可转为低频、归档或冷归档存储。配置方式与 Paimon 表相同:在控制台开启智能存储分层,或手动修改单个分区的存储类型。非分区表可手动修改整张表的存储类型。
归档存储中的数据可在所属 Bucket 开启归档直读后直接读取,也可先解冻后读取;冷归档存储中的数据须先解冻,计算引擎才能读取。
修改 Format Table
修改表结构
ALTER TABLE 只修改元数据,不重写已有文件。修改表结构请使用 ALTER TABLE,不要删表重建:删除表会删除数据,重建的表使用新的空目录。
|
操作 |
语句(Spark SQL) |
对已有数据的影响 |
|---|---|---|
|
增加字段 |
|
已有文件中没有该字段,读出为 |
|
删除字段 |
|
不再读出该字段。 |
|
重命名字段 |
|
Parquet、ORC 按字段名读取,已有文件中的字段仍为 |
|
修改字段类型 |
|
已有文件不转换。建议先在一个分区上确认已有数据仍能读取。 |
|
重命名表 |
|
仅支持在同一数据库内重命名;数据和表路径不变。 |
分区字段不支持重命名和修改类型。不要直接修改 file.format,否则已有文件会按新格式解析,导致读取失败。
修改分区字段或文件格式
如需修改 Format Table 的分区字段或文件格式,请按新的定义创建一张表,迁移数据后切换表名。旧表保留到新表验证完成:
-
按新的分区字段或文件格式创建
t_new,其他表属性与t保持一致。 -
执行
INSERT OVERWRITE t_new SELECT ... FROM t。数据量大时按分区分批执行。 -
核对两张表的行数和关键指标。
-
暂停写入
t的任务,依次执行ALTER TABLE t RENAME TO t_bak和ALTER TABLE t_new RENAME TO t,再恢复任务。 -
直接访问表路径的程序重新获取表路径。
-
确认无误后删除
t_bak。
高级配置
|
表属性 |
说明 |
默认值 |
|---|---|---|
|
|
分区目录只包含分区值(例如 |
|
|
|
写入文件的压缩算法。 |
Parquet 为 |
|
|
CSV 文件的字段分隔符。 |
|
删除数据表
表被删除后,系统默认将表内数据保留1天,以降低误删除风险。超过1天后,数据将被彻底删除。
在数据库列表中,单击数据库名称,可查看表列表。
在表列表中,单击操作列的删除。
在弹出的提示框中,单击确定,完成数据表删除。
删除后的数据表在元数据保护期内可以恢复。具体操作,请参见回收站。