# CREATE FOREIGN TABLE (GDS导入导出) #### 功能描述 在当前数据库创建一个GDS外表，用于数据并行导入导出。GDS外表分为只读外表和只写外表，分别用于数据并行导入和并行导出，缺省为只读外表。 **GDS**是一款运行在Linux操作系统的命令行工具，通过和外表机制的配合，实现数据的高速导入导出。GDS工具包需要安装在数据源文件所在的服务器上，数据源文件所在的服务器称为数据服务器，也叫GDS服务器。 安装和配置GDS，请参见[安装配置和启动GDS](https://support.huaweicloud.com/tg-dws/dws_07_0759.html)。 #### 注意事项 - 仅系统管理员dbadmin角色或已授权了USEFT权限的普通用户可执行外表操作。 ``` ALTER USER user_name USEFT; ``` - GDS外表不需要显式指定分布方式，默认支持ROUNDROBIN分布方式。 - 对于GDS外表指定任何约束（列约束、表约束等）均不生效。 - GDS导入导出支持的文件格式：TEXT、CSV和FIXED。 #### 语法格式 ``` CREATE FOREIGN TABLE [ IF NOT EXISTS ] table_name ( [ { column_name type_name POSITION(offset,length) | LIKE source_table } [, ...] ] ) SERVER gsmpp_server OPTIONS ( { option_name ' value ' } [, ...] ) [ { WRITE ONLY | READ ONLY }] [ WITH error_table_name | LOG INTO error_table_name] [REMOTE LOG 'name'] [PER NODE REJECT LIMIT 'value'] [ TO { GROUP groupname | NODE ( nodename [, ... ] ) } ]; ``` #### 参数说明 表1CREATE FOREIGN TABLE (GDS导入导出)参数说明 | 参数 | 描述 | 取值范围 | |:---|:---|:---| | IF NOT EXISTS | 如果已经存在相同名称的表，系统不会报错，而会发出一个通知，告知表关系已存在。 | - | | table_name | 外表的表名。 | 字符串，要符合标识符的命名规范。参见[标识符命名规范](https://support.huaweicloud.com/sqlreference-dws/dws_06_0007.html#ZH-CN_TOPIC_0000001811634529__section1475018612353)。 | | column_name | 外表中的字段名。 | 字符串，要符合标识符的命名规范。参见[标识符命名规范](https://support.huaweicloud.com/sqlreference-dws/dws_06_0007.html#ZH-CN_TOPIC_0000001811634529__section1475018612353)。 | | type_name | 字段的数据类型。 | - | | POSITION(offset,length) | 在固定长度模式中，定义每一个字段在数据文件中的位置。 offset为该字段在数据源文件中的起始位置，length为该字段的长度。 | offset取值不能小于0字节，单位为字节。 每条记录的长度不能大于1GB，文件中没有出现的列默认以空值代替。 | | SERVER gsmpp_server | 外表的server名字。对于GDS外表，其server是初始数据库默认创建的，即gsmpp_server。 | - | | OPTIONS | 用于指定外表数据的各类参数。 | - 数据格式参数：参见[表2]。 - 容错性参数：参见[表3]。 - 性能参数：参见[表4]。 | | READ ONLY | 只读外表，该参数只供数据导入使用。 | - | 表2OPTIONS数据格式参数说明 | 参数 | 描述 | 取值范围 | |:---|:---|:---| | location | 外表的数据源位置，目前支持URL方式的描述。多个URL使用'\|'分隔。 gds目前可以支持导出的时候自动创建外表定义的目录。 如外表location定义"gsfs:// 192.168.0.91:5000/2019/09"执行导出任务的时候，如果gds数据目录下的子目录"2019/09"不存在则会自动的创建该子目录，不需要用户手动创建外表中指定的目录。 | - 对于使用GDS从远端服务器并行导入时的只读外表（默认为只读）的URL末尾必须指定文件的匹配模式或者文件名。 例如: gsfs://192.168.0.90:5000/\*或者file:///data/data.txt或者gsfs:// 192.168.0.90:5000/\* \| gsfs:// 192.168.0.91:5000/\* - 对于使用GDS并行导出到远端服务器时的只写外表，URL不需要指定文件名。当导出数据文件存储位置为远端URL时，例如gsfs:// 192.168.0.90:5000/，则数据源位置可指定多个，此时：若导出数据文件存储位置数量小于等于数据节点数量时，使用此外部表执行导出任务，数据将被平均分配至各数据源位置；若导出数据存储位置数量大于数据节点数量时，执行导出任务，数据将被平均分配给此位置列表中从前端开始等于数据节点数量的数据源位置下，剩余数据源位置仍会创建数据文件，但文件中不会有任何数据。 - 对于使用GDS从远端服务器并行导入时的只读外表，URL个数应小于DN个数，且不能使用多个location相同的URL。 - 当使用gsfss协议，即当URL为"gsfss://"开头，进行加密导入导出时，并发数量不能超过10。 - gds导出时location指定的文件路径"gsfs://127.0.0.1:7789/2019/09/"中的2019/09子目录会在执行导出任务的时候自动创建。 - 设置file_type为"pipe"时，GDS会根据URL中最后一个字符是否为"/"来判断导入导出的目标是管道文件还是目录。如： - gsfs://192.168.0.90:5000/a/b，GDS会将b识别成一个管道文件。 - gsfs://192.168.0.90:5000/a/b/，GDS将b识别成一个目录，并在b目录下创建管道文件。 | | format | 外表中数据源文件的格式。 | 取值范围：CSV、TEXT、FIXED，缺省值为TEXT。 - CSV格式的文件，对一些转义序列按照普通字符串进行处理，因此可以有效处理数据列中的换行符。 - TEXT格式的文件，可以有效处理一些转义序列，因此无法正确处理数据列中的换行符。 - FIXED格式的文件，适用于每条数据的数据列都比较固定的数据，长度不足的列会添加空格补齐。 说明： - 转义序列指的是反斜杠开头的字符串，包括：\\b（退格）、\\f（换页）、\\n（换行）、\\r（回车）、\\t（横向制表）、\\v（纵向制表）、\\数字（八进制编码）、\\x数字（十六进制编码）。TEXT格式可以按照本身含义进行处理，其他格式只能按照普通字符串进行处理。 - 定长格式（FIXED）定义如下。当为FIXED时，必须为每一列指定POSITION。 1. 每条记录的每个字段长度相同。 2. 长度不足的字段以空格填充，数字类型字段左对齐，字符字段右对齐。 3. 字段和字段之间没有分隔符。 | | header | 指定导出数据文件是否包含标题行，标题行一般用来描述表中每个字段的信息。header只能用于CSV，FIXED格式的文件中。 在导入数据时，如果header选项为on，则数据文件中第一行会被识别为标题行，会忽略此行。如果header为off，而数据文件中第一行会被识别为数据。 在导出数据时，如果header选项为on，则需要指定**fileheader**。fileheader用来指定导出头文件的格式。如果header为off，则导出数据文件不包含标题行。 | true/on，false/off。缺省值为false/off。 | | fileheader | 指定导出数据要包含的标题行定义的文件，文件一般只包含一行用来描述每一列数据信息的字符串。 例如：在包含商品信息的数据前加标题行，定义文件如下 The information of products.\\n | - 标题行定义文件仅在header为on或true的情况下有效，且需要提前写好备用。 - 在Remote导出模式下，定义文件必须放在GDS的工作目录（即启动gds时指定的-d路径）下。 - 定义文件只能包含一行标题信息，并以换行符结尾，多余的行将被丢弃（标题信息不能包含换行符）。 - 定义文件包括换行符在内长度不超过1MB。 | | out_filename_prefix | 指定write only外表导出时，GDS端生成导出数据文件的文件名前缀。 file_type设置为pipe时，会生成"dbName_schemaName_foreignTableName.pipe"的管道文件。 如果out_filename_prefix和location中都指定了管道名，则以location中指定的管道文件名为准。 | - 指定文件名前缀需合法，符合GDS部署物理环境使用的文件系统的约束，否则出现文件创建失败： - 指定的导出文件名前缀中不含有非法字符（/、?、\*、:、\|、\\\\、\<、\>、@、#、$、\&、(、)、+以及-），其中非法字符包含但不限于以上列举，允许的字符范围为小写字母（a\~z）、大写字母（A\~Z）、数字（0\~9）和下划线（_）。 - 指定的导出文件名前缀中不可以是一些Windows和linux预留的特性字段，其中包括但不限于：con、aux、nul、prn、com0、com1、com2、com3、com4、com5、com6、com7、com8、com9、lpt0、lpt1、lpt2、lpt3、lpt4、lpt5、lpt6、lpt7、lpt8或lpt9。 - 指定的导出文件名前缀，与GDS -d目录和".dat"或者".pipe"拼接为绝对路径后必须符合GDS所在部署文件系统的文件名长度要求。 - 指定的导出文件名前缀，需要可以被数据文件的最终接收方正确解析识别（包括但不限于GDS再次导入库中），对于造成文件名解析问题的指定选项，需要用户识别。 - 在多文件同时导出的高并发导出场景下，请确认并发的导出任务不要使用同一个文件名前缀设定，否则从操作系统/文件系统层面可能会出现导出文件的覆盖和丢失。 | | delimiter | 指定数据文件行数据的字段分隔符，不指定则使用默认分隔符，TEXT格式的默认分隔符是水平制表符（tab），CSV格式的默认分隔符为","，FIXED格式没有分隔符。 | 支持多字符分隔符，但分隔符不能超过10个字节。 - 分隔符不能是\\r和\\n。 - 分隔符不能和null参数相同，CSV格式数据的分隔符不能和quote参数相同。 - TEXT格式数据的分隔符不能包含： \\.abcdefghijklmnopqrstuvwxyz0123456789。 - 数据文件中单行数据长度需\<1GB，如果分隔符较长且数据列较多的情况下，会影响导出有效数据的长度。 - 分隔符推荐使用多字符（例如'$\^\&'）和不可见字符（例如0x07、0x08、0x1b等）。 - 建议TEXT格式下多字符分隔符中的字符不要完全相同，例如不建议使用delimiter '---' 。 | | quote | 用于设置将CSV格式数据源文件中的什么字符识别为引号字符。缺省值为双引号。 | - quote参数不能和分隔符、null参数相同。 - quote参数只能是单字节的字符。 - 推荐不可见字符作为quote，例如0x07，0x08，0x1b等。 | | escape | 用来指定CSV格式的数据源文件中，什么字符为逃逸字符。逃逸字符只能指定为单字节字符。 缺省值和quote相同。 | - | | null | 用来指定数据文件中空值的表示。 | - 在TEXT格式下缺省值是\\N。 - CSV格式下缺省值是一个没有引号的空字符串。 - null值不能是\\r和\\n，最大为100个字符。 - null值不能和分隔符、quote参数相同。 | | blank_number_str_to_null | 用来指定数据文件中数值类型（INT1OID、INT2OID、INT4OID、INT8OID、FLOAT4OID、FLOAT8OID）不定数量的空格转换为NULL值。该参数仅8.2.1.236及以上集群版本支持。 例如，设置该选项为true时，定义null ''，null ' '（一个空格）、null ' '（两个空格）时都返回NULL值。 | true/false，默认值为false，表示不做转换。 | | noescaping | TEXT格式下，不对'\\'和后面的字符进行转义。 | noescaping参数只在TEXT格式下有效。true/on，false/off。缺省值为false/off。 | | encoding | 指定数据文件的编码格式名称，即需要以何编码格式对数据文件进行解析和校验/输出文件为何种编码格式。缺省值为当前数据库的默认客户端编码格式，即client_encoding。 导入外表此处强烈建议指定为文件的编码格式，或根据文件的字符集在导入前对client_encoding进行设置。否则可能会导致不必要的解析、校验错误以及其导致的导入报错回滚，甚至非法数据入库。导出外表同样希望指定此选项，以避免导出采用默认字符集设置时与预期不符。 在创建外表时此选项未指定，会在客户端给出对应Warning信息。 | - 目前GDS导入外表不支持解析带有多种字符集编码格式混合的文件，GDS导出外表不支持写出带有多种字符集编码格式混合的文件。 - 常用的编码格式有UTF8、GBK、GB18030，其中GB18030有两个版本，GB18030和GB18030_2022。GB18030_2022，用于支持汉字最新的国家标准**GB 18030-2022**。 | | dataencoding | 用于指定数据在latin1数据库表中的实际编码，实现GDS导入导出时数据从dataencoding与encoding之间的转换。该参数仅8.2.0及以上集群版本支持。 | GBK、GB18030、GB18030_2022、UTF8。 典型场景： 1. 将GB编码的文本数据导入到latin1库中并转换为UTF8编码，设置dataencoding为 'UTF8'，encoding为 'GB'。 2. 将latin1库中GB编码的数据导出为UTF8的数据文件，设置dataencoding为 'GB'，encoding为 'UTF8'。 注意： - 该参数仅支持在latin1的库中使用。 - 使用该参数时，encoding参数的取值范围也被限定在GBK、GB18030、GB18030_2022和UTF8之内。 | | mode | 指定数据导入过程中，数据导入策略。DWS只支持Normal策略。 | 取值范围： - Normal（缺省值）：支持所有文件格式(包括CSV、TEXT、FIXED)，数据导入需要在数据服务器上启动GDS协助完成。 | | eol | 指定导入导出数据文件换行符样式。 | 取值范围：支持多字符换行符，但换行符不能超过10个字节。常见的换行符，如\\r、\\n、\\r\\n（设成0x0D、0x0A、0x0D0A效果是相同的），其他字符或字符串，如$、#。 - eol参数一般用于TEXT格式的导入导出，不支持CSV格式和FIXED格式导入。为了兼容原有eol参数，仍然支持导出CSV格式和FIXED格式时指定eol参数为0x0D或0x0D0A。 - 导出FIXED格式时可指定eol参数为空串''，这样会将FIXED格式数据导出为一行，但是这种方式导出的数据不支持再通过同样的方式导入到DWS数据库中。 - eol参数不能和分隔符、null参数相同。 - eol参数不能包含：数字，字母和符号"."。 | | conflict_delimiter | 此参数一般配合**compatible_illegal_chars**参数一起使用，当用户的数据文件中包含半个汉字字符的时候，并且这半个字符和分隔符会由于外表的编码和数据库编码不一致被编码成一个其他的汉字，导致分隔符被掩盖从而报错缺少字段。 如果用户不希望让这半个字符和分隔符编码成一个其他字符则可以使用此参数。 | 取值范围：true/on，false/off。缺省值为false/off。 - 参数为true/on，允许这半个字符和分隔符编码成一个其他字符。 - 参数为false/off，不允许这半个字符和分隔符编码成一个其他字符。 此参数默认关闭。由于场景较少出现，不建议打开。如果未能识别场景而打开此参数则会有入表信息错乱的风险。 例如：假设有一行GBK数据"3\|+\|膢+\|20191212"要被导入到UTF8的数据库，用户自定义的字段分隔符为"\|+\|"。 这行GBK数据和十六进制对应关系如下 ``` 33 7C 2B 7C C4 7C 2B 7C 323031393132313 ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ 3 | + | ** | + | 20191212 ``` 当导入UTF8数据库时，数据库会发生如下转换。 ``` GBK -> UTF8 33->33 (3) 7C->7C (|) 2B->2B (+) 7C->7C(|) C47C-> E886A2(膢) 2B->2B(+) 7C->7C(|) 323031393132313-> 20191212 ``` 由于用户定义的字段分隔符号为"\|+\|"，因此对该行数据分隔后获取的数据是3，膢+\|20191212, 实际上用户可能要获得的是3，？,20191212。 "膢" 这个字符其实是一个用户不期望的半个字符，和用户定义的分隔符"\|+\|"中的"\|"产生了冲突，导致数据错乱或者导入失败。 如果用户想要忽略这种字符可以使用conflict_delimiter配合**compatible_illegal_chars**参数将"C4"这个半个GBK字符转换成"？"导入UTF8数据库。 | | file_type | 指定导入或者导出的文件类型。 | 取值范围：normal，pipe，interconn。缺省为normal。 - 参数为normal，表示导入或者导出的文件类型为普通文件。 - 参数为pipe，表示导入或者导出的文件类型为命名管道文件。 - 参数为interconn，表示当前的GDS外表用于互联互通压缩导入导出，该参数必须配合gds_compress参数使用，仅8.2.0及以上集群版本支持。 注意： 当file_type的参数为interconn时，gds需要升级到8.2.0及以上版本，否则会出现ERROR: un-support format报错。 | | auto_create_pipe | 用于设置GDS进程是否自动创建命名管道文件。 设置auto_create_pipe参数时，file_type必须设置为pipe或者interconn，否则不能成功创建外表。 | 取值范围：true/on，false/off。缺省值为true/on。 - 参数为true/on，表示允许GDS进程自动创建命名管道文件。 - 参数为false/off，表示用户需手动创建命名管道文件。 - auto_create_pipe设置为false，执行导入导出时，若未指定管道文件，会打开"数据库名_模式名_外表名.pipe"文件；若已指定管道文件，会打开location参数中指定的管道文件。该命名管道文件在pipe-timeout参数设置的时间内没有被其他程序写入或者以写的方式打开，则导入导出任务报错超时。若发现该文件不是管道文件则导入导出任务直接报错。 - auto_create_pipe设置为true，执行导入导出时，若未指定管道文件，会打开"数据库名_模式名_外表名.pipe"文件；若该文件为普通文件类型，则导入导出任务报错。若为管道文件会自动删除该文件，并重新创建该命名管道文件。 - 管道文件导出时location参数可以指定导出的管道文件，如：location'gsfs://127.0.0.1:7789/aa.pipe'，当auto_create_pipe设置为true，GDS会自动在数据目录下创建"aa.pipe"管道文件。 | | del_pipe | 用于设置不落地导入/导出业务结束后是否自动删除管道文件。 设置del_pipe时，file_type必须设置为pipe或者interconn，否则不能成功创建外表。 | 取值范围：true/on，false/off。缺省值为true/on。 - 参数为true/on，表示允许GDS进程自动删除命名管道文件。 - 参数为false/off，表示GDS进程不会删除命名管道文件。 | | gds_compress | 该参数用于降低用户使用GDS管道文件时集群之间互联互通的网络带宽，当前仅支持snappy算法。该参数仅8.2.0及以上集群版本支持。 | 取值范围：snappy。 当前仅支持snappy算法，表示GDS管道导入导出的数据是以snappy算法压缩和解压缩的。 - 设置该参数时，file_type参数必须为interconn，format必须为CSV， 默认不压缩。当前仅支持设置为snappy，使用该功能时需要保证本地集群，远端集群，GDS的版本至少在同一版本。 - 当file_type的参数为interconn时，gds需要升级到8.2.0及以上版本，否则会出现ERROR: un-support format报错。 - 该参数会降低集群间的网络带宽，但是会增加集群的CPU负载，用户可以根据实际情况选择是否开启该参数。 - 为了实现GDS互联互通外表迁移数据时，数据在网络层压缩传输，GDS外表必须支持该参数，用户不仅可以使用互联互通外表进行数据压缩迁移，也可以手动使用GDS外表实现数据在网络层压缩迁移，由于手动实现时需要用户设置参数较多，推荐使用互联互通外表的方案。 - 导入和导出端的外表必须都指定该参数。 | | preserve_blanks | 用于定长导入时，控制每列数据拖尾的空白字符（包括空格，\\t，\\v，\\f）是否保留。该参数仅8.2.0.100及以上集群版本支持。 | 取值范围：true/on，false/off。缺省值为false/off。 - 参数为true/on，表示针对BYTEAOID、CHAROID、NAMEOID、TEXTOID、BPCHAROID、VARCHAROID、NVARCHAR2OID、CSTRINGOID对应类型的列数据，保留拖尾 \\t，不进行修剪。 - 参数为false/off，表示针对所有数据类型的数据拖尾的空白字符（包括空格，\\t，\\v，\\f）进行修剪。 | | fix | 指定每一行定长格式数据的长度。按字节计算。此语法仅对READ ONLY的外表有效。 | 取值范围：N \>= POSITION指定的总长度（总长度即为表定义最后一个字段的offset与length的和）AND N \< 1GB | | out_fix_alignment | 定长导出中，指定BYTEAOID、CHAROID、NAMEOID、TEXTOID、BPCHAROID、VARCHAROID、NVARCHAR2OID、CSTRINGOID对应类型所在列的对齐方式。 | 取值范围：align_left、align_right 默认值：align_right 注意： 由于bytea数据类型要求十六进制格式（如"\\XXXX"）或八进制格式（如"\\XXX\\XXX\\XXX"），导入时需要左对齐（即列数据以两种格式开头，而非空格）。因此若导出文件需要重新以GDS外表入库且数据长度小于外表formatter指定长度，导出时需要指定左对齐，否则会在入库的过程中报错。 | | out_fix_num_alignment | 定长导出中，指定数值类型TINYINT、SMALLINT、INTEGER、BINARY_INTEGER、BIGINT、NUMERIC\[(p\[,s\])\]、DECIMAL\[(p\[,s\])\]、NUMBER\[(p\[,s\])\]、REAL、FLOAT4、DOUBLE PRECISION、FLOAT8、FLOAT\[(p)\]、BINARY_DOUBLE、DEC\[(p\[,s\])\]、INTEGER\[(p\[,s\])\]、SMALLSERIAL、SERIAL、BIGSERIAL对应类型所在列的对齐方式。该选项仅9.1.0及以上集群版本支持。 | 取值范围：align_left、align_right 默认值：align_left | | date_format | 导入对于DATE类型指定格式。此语法仅对READ ONLY的外表有效。 | 取值范围：合法DATE格式。可参考[时间日期函数和操作符](https://support.huaweicloud.com/sqlreference-dws/dws_06_0035.html)。 注意： 对于指定为ORACLE兼容类型的数据库，则DATE类型内建为TIMESTAMP类型。在导入的时候，若需指定格式，可以参考下面的timestamp_format参数。 | | time_format | 导入对于TIME类型指定格式。此语法仅对READ ONLY的外表有效。 | 取值范围：合法TIME格式，不支持时区。可参考[时间日期函数和操作符](https://support.huaweicloud.com/sqlreference-dws/dws_06_0035.html)。 | | timestamp_format | 导入对于TIMESTAMP类型指定格式。此语法仅对READ ONLY的外表有效。 | 取值范围：合法TIMESTAMP格式，不支持时区。可参考[时间日期函数和操作符](https://support.huaweicloud.com/sqlreference-dws/dws_06_0035.html)。 | | smalldatetime_format | 导入对于SMALLDATETIME类型指定格式。此语法仅对READ ONLY的外表有效。 | 取值范围：合法SMALLDATETIME格式。可参考[时间日期函数和操作符](https://support.huaweicloud.com/sqlreference-dws/dws_06_0035.html)。 | 表3OPTIONS容错性参数说明 | 参数 | 描述 | 取值范围 | |:---|:---|:---| | fill_missing_fields | 当数据导入时，若数据源文件中一行的最后一个字段缺失的处理方式。 | 取值范围：true/on，false/off。缺省值为false/off。 - 参数为true/on，当数据导入时，若数据源文件中一行数据的最后一个字段缺失，则把最后一个字段的值设置为NULL，不报错。 - 参数为false/off，如果最后一个字段缺失会显示如下错误信息。 ``` missing data for column "tt" ``` | | ignore_extra_data | 若数据源文件比外表定义列数多，是否会忽略对多出的列。该参数只在数据导入过程中使用。 | 取值范围：true/on，false/off。缺省值为false/off。 - 参数为true/on，若数据源文件比外表定义列数多，则忽略行尾多出来的列。 - 参数为false/off，若数据源文件比外表定义列数多，会显示如下错误信息。 ``` extra data after last expected column ``` 注意： 如果行尾换行符丢失，使两行变成一行时，设置此参数为true将导致后一行数据被忽略掉。 | | reject_limit | 指定本次数据导入允许出现的数据格式错误个数，当导入过程中出现的数据格式错误未达到限定值时，本次数据导入可以成功。 说明： 此语法建议用PER NODE REJECT LIMIT 'value'替代。 数据格式错误是指缺少或者多出字段值，数据类型错误或者编码错误。对于非数据格式错误，一旦发生就将导致整个数据导入失败。 | 取值范围：正整型值、unlimited（无限制）。指定正整型参数时需要添加单引号。 不指定该参数时，有错误信息立即返回。 | | compatible_illegal_chars | 导入导出非法字符容错参数。此语法对READ ONLY和WRITE ONLY的外表有效。 导出容错仅8.1.3.331及以上版本集群支持。 | 取值范围：true/on，false/off。缺省值为false/off。 - 参数为true/on，则导入导出时遇到非法字符进行容错处理，非法字符转换后入库或出库，不报错，不中断导入导出。 - 参数为false/off，导入导出时遇到非法字符进行报错，中断导入。 - 导入非法字符容错规则如下： - 对于'\\0'，容错后转换为空格。 - 对于其他非法字符，容错后转换为问号。 - 如果compatible_illegal_chars为true/on标识导入时对于非法字符进行容错处理，如果NULL、DELIMITER、QUOTE、ESCAPE设置为空格或问号则会通过如"illegal chars conversion may confuse COPY escape 0x20"等报错信息提示用户修改可能引起混淆的参数，以避免导入错误。 - 需注意：导出外表容错参数开启后，非法字符数据导出被容错为问号，再次导入回DWS库中就会与原数据不一致。 | | replace_illegal_chars | 导入非法字符容错参数，用于将'\\0'替换为指定字符串。此语法仅对READ ONLY的外表有效。 | 指定用于替换'\\0'的字符串有如下约束： - 仅支持compatible_illegal_chars参数为true/on时设置。 - 仅支持format参数为TEXT或CSV时设置。 - 字符串长度不能超过10。 - 字符串不能与delimiter相同或者包含delimiter，不能包含以下字符：数字，字母以及特殊字符"\\"和"."。 | | WITH error_table_name | 数据导入过程中出现的数据格式错误信息将被写入error_table_name指定的错误信息表中，可以在并行导入结束后查询此错误信息表，获取详细的错误信息。此参数只在设置了reject_limit参数时有效。 说明： 如果为了兼容postgres开源接口，此语法建议用LOG INTO代替。 | 字符串，要符合标识符的命名规范。 | | LOG INTO error_table_name | 数据导入过程中出现的数据格式错误信息将被写入error_table_name指定的错误信息表中，可以在并行导入结束后查询此错误信息表，获取详细的错误信息。 说明： 若没有指定PER NODE REJECT LIMIT参数，则此参数不起作用。 | 字符串，要符合标识符的命名规范。 | | REMOTE LOG 'name' | 数据导入过程中出现的数据格式错误信息将被写到GDS端以文件方式保存。name为错误数据文件的文件名前缀。 | - | | PER NODE REJECT LIMIT 'value' | 指定本次数据导入过程中每个DN实例上允许出现的数据格式错误的数量，如果有一个DN实例上的错误数量大于设定值，本次导入失败，报错退出。 注意： 此语法指定的是单个节点的错误容忍度。 数据格式错误是指缺少或者多出字段值，数据类型错误或者编码错误。对于非数据格式错误，一旦发生就将导致整个数据扫描失败。 | 整型值，unlimited（无限），不指定该参数时，有错误信息立即返回。 | 表4OPTIONS性能参数说明 | 参数 | 描述 | 取值范围 | |:---|:---|:---| | file_sequence | 用于多任务GDS外表并行导入，提升单个文件的导入性能。该参数仅供数据导入使用。 格式为file_sequence '文件被拆分的总数-当前分片' 。例如： file_sequence '3-1' 表示导入的文件在逻辑上被拆分成3份，当前外表导入的数据为第一个分片上的数据。 file_sequence '3-2' 表示导入的文件在逻辑上被拆分成3份，当前外表导入的数据为第二个分片上的数据。 file_sequence '3-3' 表示导入的文件在逻辑上被拆分成3份，当前外表导入的数据为第三个分片上的数据。 | 使用该参数需遵循以下约束： - 文件被拆分的总数小于等于8。 - 当前分片小于等于文件被拆分的总数。 - 导入的文件仅支持CSV和text格式。 使用CSV格式进行并行导入时，在某些场景中会因为CSV本身的规则和GDS拆分逻辑冲突而导致其中的某些分片导入失败，详情参见[使用file_sequence参数异常场景说明]。 | #### 示例 创建外表customer_ft，用来以TEXT格式导入GDS服务器10.10.123.234上的数据： ``` DROP FOREIGN TABLE IF EXISTS customer_ft; CREATE FOREIGN TABLE customer_ft ( c_customer_sk integer , c_customer_id char(16) , c_current_cdemo_sk integer , c_current_hdemo_sk integer , c_current_addr_sk integer , c_first_shipto_date_sk integer , c_first_sales_date_sk integer , c_salutation char(10) , c_first_name char(20) , c_last_name char(30) , c_preferred_cust_flag char(1) , c_birth_day integer , c_birth_month integer , c_birth_year integer , c_birth_country varchar(20) , c_login char(13) , c_email_address char(50) , c_last_review_date char(10) ) SERVER gsmpp_server OPTIONS ( location 'gsfs://10.10.123.234:5000/customer1*.dat', FORMAT 'TEXT' , DELIMITER '|', encoding 'utf8', mode 'Normal') READ ONLY; ``` 创建外表foreign_HR_staffs_ft，用来以TEXT格式导入GDS服务器192.168.0.90和192.168.0.91上的数据，导入过程错误信息将记录到err_HR_staffs中。本次数据导入允许出现的数据格式错误个数为2。 ``` DROP FOREIGN TABLE IF EXISTS foreign_HR_staffs_ft; CREATE FOREIGN TABLE foreign_HR_staffs_ft ( staff_ID NUMBER(6) , FIRST_NAME VARCHAR2(20), LAST_NAME VARCHAR2(25), EMAIL VARCHAR2(25), PHONE_NUMBER VARCHAR2(20), HIRE_DATE DATE, employment_ID VARCHAR2(10), SALARY NUMBER(8,2), COMMISSION_PCT NUMBER(2,2), MANAGER_ID NUMBER(6), section_ID NUMBER(4) ) SERVER gsmpp_server OPTIONS (location 'gsfs://192.168.0.90:5000/* | gsfs://192.168.0.91:5000/*', format 'TEXT', delimiter E'\x08', null '',reject_limit '2') WITH err_HR_staffs_ft; ``` 建立外表，用来以CSV格式导入input_data目录下存放在各个节点名文件下的所有文件。 ``` DROP FOREIGN TABLE IF EXISTS foreign_HR_staffs_ft1; CREATE FOREIGN TABLE foreign_HR_staffs_ft1 ( staff_ID NUMBER(6) , FIRST_NAME VARCHAR2(20), LAST_NAME VARCHAR2(25), EMAIL VARCHAR2(25), PHONE_NUMBER VARCHAR2(20), HIRE_DATE DATE, employment_ID VARCHAR2(10), SALARY NUMBER(8,2), COMMISSION_PCT NUMBER(2,2), MANAGER_ID NUMBER(6), section_ID NUMBER(4) ) SERVER gsmpp_server OPTIONS (location 'file:///input_data/*', format 'csv', quote E'\x08', mode 'private', delimiter ',') WITH err_HR_staffs_ft1; ``` 建立外表，用来以CSV格式导出数据到output_data目录下。 ``` DROP FOREIGN TABLE IF EXISTS foreign_HR_staffs_ft2; CREATE FOREIGN TABLE foreign_HR_staffs_ft2 ( staff_ID NUMBER(6) , FIRST_NAME VARCHAR2(20), LAST_NAME VARCHAR2(25), EMAIL VARCHAR2(25), PHONE_NUMBER VARCHAR2(20), HIRE_DATE DATE, employment_ID VARCHAR2(10), SALARY NUMBER(8,2), COMMISSION_PCT NUMBER(2,2), MANAGER_ID NUMBER(6), section_ID NUMBER(4) ) SERVER gsmpp_server OPTIONS (location 'file:///output_data/', format 'csv', quote E'\x08', delimiter '|', header 'on') WRITE ONLY; ``` #### 使用file_sequence参数异常场景说明 使用CSV格式进行并行导入时，在如下示例场景中会因为CSV本身的规则和GDS拆分逻辑冲突而导致其中的某些分片导入失败。 **场景**：csv文件中包含未转义的换行符，且该换行符被quote指定的字符所包含，并且该行数据处于逻辑分片的第一行。 **示例**：并行导入一个文件big.csv ，正确导入显示内容如下： ``` --id, username, address 10001,"customer1 name","Rose District" 10002,"customer2 name"," 23 Road Rose District NewCity" 10003,"customer3 name","NewCity" ``` 文件被拆分成两份后，第一个分片显示内容如下： ``` 10001,"customer1 name","Rose District" 10002,"customer2 name"," 23 ``` 第二个分片显示内容如下： ``` Road Rose District NewCity" 10003,"customer3 name","NewCity" ``` 因为第二个分片第一行后面的换行符包含在一个双引号之间，导致GDS无法分辨该换行符是字段中的换行符还是行中的分隔符，因此第一个分片会成功导入两条数据，第二个分片导入失败。 #### 相关链接 [ALTER FOREIGN TABLE (GDS导入导出)](https://support.huaweicloud.com/sqlreference-dws/dws_06_0123.html)，[DROP FOREIGN TABLE](https://support.huaweicloud.com/sqlreference-dws/dws_06_0192.html) [安装和启动GDS](https://support.huaweicloud.com/tg-dws/dws_07_0759.html) 最佳实践：[使用GDS从远端服务器上导入表数据到DWS集群](https://support.huaweicloud.com/bestpractice-dws/dws_05_0032.html) 常见问题：[GDS导入/导出类问题](https://support.huaweicloud.com/trouble-dws/dws_09_0056.html)