Format Table

更新时间:
复制 MD 格式

本文介绍 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控制台

  1. 登录数据湖构建控制台

  2. 在数据目录列表页面,单击Catalog名称,进入Catalog详情页。

  3. 在数据库列表中,单击数据库名称,进入表列表页。

  4. 在表列表中,单击新建数据表。

  5. 配置以下信息,单击确定。

    配置项

    说明

    表格式

    选择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

  1. 在数据库列表中,单击数据库名称,可查看表列表。

  2. 在表列表中,单击表名称,可查看表字段。

  3. 单击表详情页签,可查看数据表基本信息、字段列表及分区定义。

  4. 单击权限页签,可为用户或角色授予数据表相关权限。详情请参见数据授权管理。

写入和读取数据

可通过 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。

控制台

  1. 在数据库的表列表中,单击目标 Format Table,在文件列表页签进入目标分区目录,例如 dt=20261105/。对于已开启托管分区的表,分区目录不存在时,先执行 ADD PARTITION 创建。

  2. 上传与表定义的文件格式、字段一致的文件。文件名不要以 . 或 _ 开头。

  3. 向已开启托管分区的表上传文件后,执行 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、控制台上传文件等方式写入后需要手动登记。

表目录下所有分区目录

分区过期清理、存储分层

支持

不支持

ADD PARTITION、DROP PARTITION、MSCK REPAIR TABLE、ANALYZE TABLE

支持

不支持

分区很多时的查询规划

从 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)

对已有数据的影响

增加字段

ALTER TABLE t ADD COLUMNS (c STRING)

已有文件中没有该字段,读出为 NULL。

删除字段

ALTER TABLE t DROP COLUMN c

不再读出该字段。

重命名字段

ALTER TABLE t RENAME COLUMN a TO b

Parquet、ORC 按字段名读取,已有文件中的字段仍为 a,重命名后 b 读出为 NULL。

修改字段类型

ALTER TABLE t ALTER COLUMN c TYPE BIGINT

已有文件不转换。建议先在一个分区上确认已有数据仍能读取。

重命名表

ALTER TABLE t RENAME TO t2

仅支持在同一数据库内重命名;数据和表路径不变。

重要

分区字段不支持重命名和修改类型。不要直接修改 file.format,否则已有文件会按新格式解析,导致读取失败。

修改分区字段或文件格式

如需修改 Format Table 的分区字段或文件格式,请按新的定义创建一张表,迁移数据后切换表名。旧表保留到新表验证完成:

  1. 按新的分区字段或文件格式创建 t_new,其他表属性与 t 保持一致。

  2. 执行 INSERT OVERWRITE t_new SELECT ... FROM t。数据量大时按分区分批执行。

  3. 核对两张表的行数和关键指标。

  4. 暂停写入 t 的任务,依次执行 ALTER TABLE t RENAME TO t_bak 和 ALTER TABLE t_new RENAME TO t,再恢复任务。

  5. 直接访问表路径的程序重新获取表路径。

  6. 确认无误后删除 t_bak。

高级配置

表属性

说明

默认值

format-table.partition-path-only-value

分区目录只包含分区值(例如 2025/,而不是 year=2025/)时设为 true。设为 true 的表不支持生命周期管理。

false

format-table.file.compression

写入文件的压缩算法。

Parquet 为 snappy,ORC 为 zstd,CSV、JSON 不压缩。

csv.field-delimiter

CSV 文件的字段分隔符。

,

删除数据表

警告

表被删除后,系统默认将表内数据保留1天,以降低误删除风险。超过1天后,数据将被彻底删除。

  1. 在数据库列表中,单击数据库名称,可查看表列表。

  2. 在表列表中,单击操作列的删除。

  3. 在弹出的提示框中,单击确定,完成数据表删除。

删除后的数据表在元数据保护期内可以恢复。具体操作,请参见回收站。

常见问题

写入后,Spark 或 Flink 查询不到分区怎么办?

托管分区表只返回已登记的分区。通过 pypaimon 或控制台写入后,执行 ADD PARTITION 或 MSCK REPAIR TABLE。

开启托管分区后,查询结果为空怎么办?

已有分区尚未登记,执行 MSCK REPAIR TABLE。

重命名字段后,为什么已有数据中该字段为 NULL?

Parquet、ORC 按字段名读取,已有文件仍使用旧字段名。请按修改分区字段或文件格式中的迁移流程处理。

INSERT OVERWRITE 后,为什么其他分区变空?

未指定 PARTITION 子句时,静态覆盖写会清空整张表。指定分区,或设置 spark.sql.sources.partitionOverwriteMode=dynamic。

MSCK REPAIR TABLE 提示不支持 v2 表怎么办?

表尚未开启托管分区。设置 metastore.partitioned-table=true 后重试。

ANALYZE TABLE 的 PARTITION 子句报缺少前置分区字段怎么办?

从第一个分区字段开始指定,不能只指定后面的分区字段。

分区字段可以重命名吗?

不支持直接重命名。按修改分区字段或文件格式中的步骤新建表并迁移数据。