SeaTunnel FieldMapper 字段映射转换插件详解：重命名、排序与裁剪字段

• 数据集成
• ETL
• 大数据
• 批处理
• 流处理
• 变更数据捕获

本文基于 SeaTunnel 开源仓库的FieldMapper转换插件，系统讲解如何通过field_mapper配置在输入表与输出表之间建立字段映射关系，实现字段重命名、字段顺序调整与字段裁剪。读完本文，你将能够在 SeaTunnel 作业配置中熟练使用FieldMapper，并理解其在 Catalog 表结构、主键与约束键层面的底层实现机制。

概述：FieldMapper 能做什么

FieldMapper（字段映射）是 SeaTunnel 转换（Transform）体系中的一类字段级转换插件，其核心作用是为输入模式（input schema）与输出模式（output schema）之间添加字段映射。它的典型能力包括：

• 字段重命名：将输入字段name映射为输出字段new_name；
• 字段顺序调整：按映射定义顺序重新排列输出表的字段顺序；
• 字段裁剪（删除）：凡是不出现在field_mapper映射中的输入字段，将不会出现在输出表中。

插件在源码中的注册名为FieldMapper，对应实现类位于 FieldMapperTransform.java，其PLUGIN_NAME常量即定义为"FieldMapper"（见该文件第 47 行）。

属性配置

FieldMapper转换插件的核心配置项如下：

配置项在源码中由 FieldMapperTransformConfig.java 定义：

public static final Option<Map<String, String>> FIELD_MAPPER = Options.key("field_mapper") .mapType() .noDefaultValue() .withDescription( "Specify the field mapping relationship between input and output");

field_mapper [config]

field_mapper用于指定输入与输出之间的字段映射关系，类型为Map<String, String>，必须配置且不能为空。其语义为：

• key：输入表（源表）中的字段名；
• value：输出表（目标表）中的字段名；
• 顺序：映射条目书写的顺序即输出表中字段的排列顺序。源码中字段映射保存在LinkedHashMap中（见 FieldMapperTransformConfig.java 第 41 行），这保证了配置书写顺序与输出字段顺序严格一致。

如果某个 key 在输入表中不存在，作业会直接抛出异常。从源码看，FieldMapperTransform构造函数与transformTableSchema方法中均会对映射 key 做存在性校验，找不到输入字段时抛出TransformCommonError.cannotFindInputFieldError(...)（见 FieldMapperTransform.java 第 57-71 行、第 104-109 行）。

common options [config]

FieldMapper同样支持所有转换插件共享的编排参数，包括：

注意：旧参数名source_table_name与result_table_name已废弃，新配置请统一使用plugin_input与plugin_output。详细说明见 Transform 通用参数文档。

完整示例：重命名、排序与裁剪

假设源端数据读取到的表结构及数据如下：

我们想要完成三件事：

1. 删除age字段；
2. 调整字段顺序为id、card、name；
3. 将name重命名为new_name。

在作业配置中添加FieldMapper转换即可实现：

transform { FieldMapper { plugin_input = "fake" plugin_output = "fake1" field_mapper = { id = id card = card name = new_name } } }

执行转换后，结果表fake1中的数据将变为：

注意：age字段未出现在field_mapper中，因此在输出表中被自动裁剪；card与name的书写顺序决定了输出表id、card、new_name的字段排列顺序。

源码实现原理

FieldMapper的核心处理逻辑由 FieldMapperTransform.java 完成，它继承自AbstractCatalogSupportMapTransform，同时重写了行数据转换与表结构转换两部分。

行数据转换（transformRow）

@Override protected SeaTunnelRow transformRow(SeaTunnelRow inputRow) { Map<String, String> fieldMapper = config.getFieldMapper(); Object[] outputDataArray = new Object[fieldMapper.size()]; for (int i = 0; i < outputDataArray.length; i++) { outputDataArray[i] = inputRow.getField(needReaderColIndex.get(i)); } SeaTunnelRow outputRow = new SeaTunnelRow(outputDataArray); outputRow.setRowKind(inputRow.getRowKind()); outputRow.setTableId(inputRow.getTableId()); outputRow.setOptions(inputRow.getOptions()); return outputRow; }

可见，逐行转换时插件按照预先计算好的源字段索引needReaderColIndex从输入行取值，组装成新的输出行，并且会保留原行的RowKind（增删改标识）、TableId与Options等元信息，保证行级语义在 CDC 等场景下不丢失。

表结构转换（transformTableSchema）

PhysicalColumn outputColumn = PhysicalColumn.of( value, oldColumn.getDataType(), oldColumn.getColumnLength(), oldColumn.getScale(), oldColumn.isNullable(), oldColumn.getDefaultValue(), oldColumn.getComment(), oldColumn.getSourceType(), oldColumn.getOptions());

输出列的构建是“换名不换型”：新列只替换字段名（映射 value），而数据类型、长度、精度、可空性、默认值、注释、源类型等元数据全部继承自原输入列，因此FieldMapper不会改变字段的数据类型，只会改变字段名、顺序与数量。

主键与约束键的保留

FieldMapper在重建输出表结构时，会同步处理主键（PrimaryKey）与约束键（ConstraintKey）：

• 若输入表存在主键，且主键涉及的列全部包含在映射 key 中，则输出表会生成映射后的新主键（主键列名替换为映射后的字段名）；
• 同理，约束键（如唯一键）若其列全部在映射范围内，也会被保留并替换为新字段名。

这一行为可以通过单元测试验证：FieldMapperTransformTest.java 中构造了主键("key1", "key2")与唯一约束("key1", "key3")的输入表，在将key1 -> k1、key2 -> key2、key3 -> key3、key4 -> k4映射后断言：

• 输出表字段数为 4，字段名依次为k1, key2, key3, k4；
• 新主键列名被替换为("k1", "key2")；
• 唯一约束列名被替换为("k1", "key3")。

工厂类与配置校验

FieldMapper通过 FieldMapperTransformFactory.java 注册到 SeaTunnel 的插件体系中，其factoryIdentifier()返回"FieldMapper"，与配置中的插件名一致。

工厂类定义的OptionRule约束如下：

• 必填：field_mapper，且附加Conditions.mapNotEmpty(...)条件，即映射不能为空；
• 可选：table_transform（多表转换配置）、table_match_regex（表路径匹配正则）、rule_match_mode（规则匹配模式）。

校验逻辑有对应测试覆盖：FieldMapperTransformFactoryTest.java 验证了三种场景：

• 配置了非空field_mapper时校验通过；
• 完全缺失field_mapper时抛出OptionValidationException；
• field_mapper为空 Map 时同样抛出OptionValidationException。

这意味着在作业提交阶段，缺少映射或映射为空的FieldMapper配置会直接报错，而不是等到运行时才发现。

多表（Multi Catalog）转换支持

FieldMapper还提供了多表场景下的实现 FieldMapperMultiCatalogTransform.java。当作业包含多张 Catalog 表时，插件会为每张输入表构建独立的FieldMapperTransform实例；对于不满足匹配规则的输入表，则使用IdentityMapTransform（恒等转换）原样透传。

与之配合的通用参数定义在 TransformCommonOptions.java：

MULTI_TABLES选项的 key 为table_transform，注意与单表场景下的field_mapper区分：多表场景可针对不同的表路径分别指定映射规则。

使用建议

• 映射键必须真实存在：field_mapper中的 key 必须是输入表真实存在的字段，否则作业会抛出cannot find field类异常；
• 利用顺序特性：field_mapper的书写顺序即输出表字段顺序，可同时完成排序与裁剪，减少额外 SQL 转换的依赖；
• 注意数据类型继承：FieldMapper只做字段名/顺序/数量的映射，不改动数据类型；如需类型转换，应配合Copy、Sql等其他转换插件使用；
• 多表场景显式命名：当 pipeline 中存在分支或多表时，优先使用plugin_input/plugin_output显式声明数据集，提升可读性与可维护性。

更新日志

• 新版本：添加了复制转换连接器（Copy Transform）等相关能力，FieldMapper作为基础字段映射插件持续演进，详情可参考 Transforms 文档目录。

• 数据集成
• ETL
• 大数据
• 批处理
• 流处理
• 变更数据捕获