# 附加字段使用说明 #### 使用场景 - 用户期望在目的端表中新增一个附加字段，附加字段的值可以来自于源端某个已有字段的转换结果，也可以来源于源端、目的端库表相关的元数据。 - 用户期望通过附加字段覆盖已有同名字段的值（仅部分链路支持）。 支持的链路：多数整库作业都支持为目的端表添加附加字段，是否支持附加字段请以[使用教程](https://support.huaweicloud.com/usermanual-dataartsstudio/dataartsstudio_01_7665.html)各链路描述为准。 #### 约束限制 - 当附加字段名与源端已有字段名重名时自动建表可能会失败，提示字段名重复，用户需要手动完成建表。 - 对于已有表添加附加字段时，用户需要保证目的端表结构中已包含附加字段，否则可能会出现作业运行失败。 - 在使用UDF时，请仔细阅读[字段值配置说明]中UDF字段值的说明。 #### 配置附加字段方式 作业编辑阶段，目标端配置，刷新源表和目标表映射后可以为指定表添加附加字段。 图1配置附加字段入口 ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002419704646.png "点击放大") 附加字段需要配置包括以下内容： - 字段名称：请尽量避免使用特殊字符作为字段名内容，建议客户只使用字母、数字、下划线为附加字段命名。 - 字段类型：部分作业附加字段的字段类型选择有限，请按需选择类型。 - 字段值：当前支持的字段值类型包括常量、内置变量、字段变量、UDF方法。 自动建表时会默认将附加字段添加到目的端表结构中。 #### 字段值配置说明 - **常量** - 参数说明：字段值为常量时，附加字段填充固定值。 - 作业样例：如下图，mysql_constant_extra_col字段在目的端的查询结果为固定的AAAA。 图2常量取值示例 ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002455716297.png "点击放大") - **内置变量** - 参数说明：内置变量支持配置以下值，均为与数据源元数据相关的值： - 源端host ip地址：source. - 源端库名称：source.schema - 源端表名称：source.table - 目的端库名称：target.schema - 目的端表名称：target.table - 作业样例：如下图。 图3内置变量示例 ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002455676213.png "点击放大") 查看目的端输出结果。 图4目的端结果 ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002455716301.png "点击放大") - **字段变量** - 参数说明：字段变量会为附加字段填充源端表的某个字段值，用户可以通过下拉框选定或手动输入源端字段名。 - 作业样例：如下图。 图5字段变量取值示例 ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002421997500.png "点击放大") 源端表llch96.rds_source_tbl_961表数据如下： 图6源端表数据 ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002422157368.png "点击放大") 数据迁移到目的端后输入如下： 图7目的端表数据 ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002455716305.png "点击放大") - **UDF方法** - 参数说明：字段值选择UDF方法时，支持用户按需选择UDF转换函数对源端字段值做二次处理后写入附加字段，支持UDF方法包括： - substring: 截取源端col列的子串, 范围在\[pos, pos+len)。 - date_format: 将源端col列按time_format格式化, 可选转换时区。 - now(\[tz\])：获取指定时区的当前时间。 - if(cond_exp, str1, str2): 满足条件表达式cond_exp时返回str1, 否则返回str2。 - concat: 拼接多个参数, 可为源端列或字符串。 - from_unixtime: 将unix时间戳按time_format格式化。 - unix_timestamp: 将时间转成unix时间戳，可显式定义时间格式及转换后精度。 支持UDF之间的嵌套，例如：substring(date_format, 0, 4) 各个UDF函数的详细使用方式和样例如下: - substring substring说明： - 对源端col字段的值从第pos个字符（包含pos）开始截取，默认截取到末尾。 - 截取长度len参数可选，配置len时表示向后截取结果字符的长度为len。 - 第一个字符pos=1，第二个字符pos=2，依次类推。 - pos=0同样表示第一个字符。 ``` 设定col = "abcdefg"，长度为7 substring = "abcdefg" substring = "abc" substring = "abc" substring = "cdef" substring = "abcdefg" ``` - date_format date_format说明： - 对源端的时间格式字段col按照新的格式time_format进行格式化，可以设置源端col的时区为src_tz、目的端的时区dst_tz。 - col的值必须为时间格式，例如'2025-12-11 00:49:00.123456'，否则可能在转换时导致作业异常。 - time_format参数必须为合法的时间格式，可以包含yyyy、MM、dd、HH、mm、ss、SS，例如yyyy-MM-dd HH:mm:ss.SSS，在拼写date_format表达式时请勿用引号将time_format包裹，否则会导致作业异常。例如 date_format是合法的，date_format是非法的。 - src_tz为输入时区，表示输入时间字段col的时区，配置输入时区的表达式模板为date_format，例如 date_format，-8即为源端时区。 - dst_tz为输出时区，表示用户期望UDF输出结果时间的时区，配置输出时区的表达式模板为date_format或date_format，例如date_format、date_format均表示输出时区为+8。 - 当源端字段col类型为timestamp时，字段值已默认带有输入时区信息，配置输入时区不会生效。 - date_format，当源端col为非timestamp类型时，默认源端与目的端时区一致，不做时区转换；当源端col为timestamp类型时，默认按系统时区输出结果。 - date_format，当源端col为非timestamp类型时，默认源端时区为UTC。 表1时区生效规则 | 表达式 | 源端字段类型 | 源端生效时区 | 目的端生效时区 | |:---|:---|:---|:---| | date_format | 字符串/datetime | 当前region时区 | 当前region时区 | | date_format | timestamp | 源端时区 | 当前region时区 | | date_format | 字符串/datetime | UTC | dst_tz | | date_format | timestamp | 源端时区 | dst_tz | | date_format | 字符串/datetime | src_tz | dst_tz | | date_format | timestamp | 源端时区 | dst_tz | 字段类型为datetime类型示例： ``` 设定col = "2023-08-01 09:00:00.000000"，字段类型为datetime类型或字符串类型 #未配置时区信息，默认源端与目的端时区一致 date_format = "2023-08-01 09:00:00" #源端非timestamp字段类型，默认源端时区为UTC，这里配置目的端为UTC，源端与目的端时区一致 date_format = "2023-08-01 09:00:00" #源端非timestamp字段类型，默认源端时区为UTC，这里配置目的端时区为+8 date_format = "2023-08-01 17:00:00" date_format = "2023-08-01 17:00:00" date_format = "2023-08-01 17:00:00" #源端非timestamp字段类型，配置源端时区+1生效，配置目的端时区为+8 date_format = "2023-08-01 16:00:00" #源端非timestamp字段类型，配置源端时区-8生效，配置目的端时区为+8 date_format = "2023-08-02 01:00:00" ``` 字段类型为timestamp示例： ``` 设定col = "2023-07-05 00:00:15.123456"，字段类型为timestamp，源端时区为+8，当前华为云region所在时区为+8（例如Asia/Singapore） #源端为timestamp字段类型，源端时区为+8，目的端时区为华为云region所在时区，即+8 date_format = "2023-07-05 00:00:15" #源端为timestamp字段类型，源端时区为+8，目的端时区为配置的+16 date_format = "2023-07-05 08:00:15" #源端为timestamp字段类型，配置的src_tz不生效，使用源端真实时区+8，目的端时区为配置的+8 date_format = "2023-07-05 00:00:15" #源端为timestamp字段类型，配置的src_tz不生效，使用源端真实时区+8，目的端时区为配置的+16 date_format = "2023-07-05 08:00:15" ``` - now now(\[tz\])说明： - 数据被实时作业读取到时的系统时间。 - tz为可选配置，用来指定系统时间所在时区，默认为华为云服务当前所在region的时区。 示例： ``` now() = "2025-07-30 14:46:48.969" now(+16) = "2025-07-30 22:46:48.969" ``` - if if(cond_exp, str1, str2)说明： - 根据用户配置的逻辑判断表达式cond_exp决定输出结果，cond_exp判定结果为true时输出"str1"，cond_exp判定结果为false时输出"str2"。 - 当前仅支持对内置变量的"等于"/"不等于"的逻辑判断，逻辑判断表达式一边的常量部分需要使用英文单引号包裹，例如，if。 示例： ``` if = 'a' if = 'qaz' ``` - concat concat说明： - 将多个字段值拼接，支持对源端字段值的拼接，也支持对字符串常量的拼接，例如，concat。 - 当存在任意一个输入参数为null时整个表达式输出结果为null。 示例： ``` # col为源端字段，取值col="col_data"，#{mgr.source.table}为内置变量“源端表名”的引用，取值为#{mgr.source.table}="src_tb" concat = "col_data_src_tb" # col为源端字段，取值col="col_data"，col2源端字段，取值col2="col2_data"，第三个输入参数为一个字符串常量“aaa” concat = "col_data&col2_data_aaa" # col_null为一个全null字段，整个表达式输出结果为null concat = null ``` - from_unixtime from_unixtime说明： - 将长整型的时间戳字段转换为时间格式的值，col字段为源端长整型的unix timestamp，time_format参数为用户期望输出的时间格。 - 不支持指定输出时间的时区，默认按照当前华为云region的时区输出结果。 - 不指定time_format的场景下，默认值按照yyyy-MM-dd HH:mm:ss.SSS格式输出结果。 示例： ``` # col = 17042536161231 from_unixtime = "2024-01-03 11:46" from_unixtime = "2024-01-03 11:46:56:123100" # col= 1704253616 from_unixtime = "2024-01-03 11:46:56.000" # col= 942379893 from_unixtime = "1999-11-12" # col= 17042536161 from_unixtime = "2024-01-03" ``` - unix_timestamp unix_timestamp说明： - 将时间格式的数据转换成长整型的unix timestamp，col为源端时间格式的字段，precision参数用于配置输出unix timestamp的秒以下的精度，默认精度为3，time_format用于指定输入数据的时间格式。 - time_format用于指定输入数据的时间格式，time_format需要与col字段的格式严格匹配，否则可能出现精度丢失或转换不准确问题；当用户没有配置time_format时，会按照yyyy-MM-dd HH:mm:ss\[.fffffffff\]格式解析输入数据。 - unix_timestamp无法指定col字段的时区信息，当col字段为timestamp类型时，会使用源端时区解析输入值；当col字段为datetime或字符串时，默认使用华为云服务当前所在region的时区解析输入值。 示例： ``` # col = "2024-01-03 11:46:56.123" unix_timestamp = "1704253616123" # col = "2024-01-03 11:46:56" unix_timestamp = "1704253616000" # col = "2024-01-03 11:46:56.123456" unix_timestamp = "1704253616123456000" # col = "2024-01-03 11:46:56.123456789" unix_timestamp = "1704253616123456789" # col = "2024-01-03 11:46" unix_timestamp = "1704253560" ``` - 表达式嵌套 支持用户对UDF进行嵌套使用。 示例： ``` # col = "2025-11-11 00:14:23" substring(date_format, 0, 4) = "2025" ``` - 作业样例：如下图例。 图8源表建表结构示例 ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002455635345.png) 查看源端数据。 图9源端数据 ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002455636349.png "点击放大") 查看作业配置。 图10作业配置 ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002455636801.png "点击放大") 查看最终同步结果。 图11同步结果 ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002455518725.png "点击放大") #### 通过附加字段覆盖已有同名字段的值 部分链路支持用户配置与源表已有字段同名的附加字段以覆盖源端字段值。本场景下需要用户手动建表，不支持自动建表。 作业样例如下： 1. 查看源表建表结构。 图12源表建表结构 ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002421997516.png) 2. 查看源端数据。 图13源端数据 ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002455676233.png "点击放大") 3. 查看目的端手动建表结果。 图14目的端手动建表结果 ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002422157372.png) 4. 配置作业参数。 目的端高级配置中添加参数 sink.extra.column.first = true。 图15添加自定义参数 ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002455716309.png "点击放大") 5. 查看修改结果。 图16刷新 ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002455676237.png "点击放大") 最终目的端同步结果，age字段成功被附加字段覆盖。 图17查看修改结果 ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002455716313.png "点击放大")