# 数据并行导入导出
GaussDB提供了并行导入导出功能，以快速、高效地完成大量数据导入导出。介绍GaussDB并行导入导出的相关参数。
#### raise_errors_if_no_files
**参数说明：**设置导入时是否区分"导入文件记录数为空"和"导入文件不存在"。该参数开启时，"导入文件不存在"的时候，GaussDB将抛出"文件不存在"的错误。
**参数类型：**布尔型
**参数单位：**无
**取值范围** **：**
- on：表示导入时区分"导入文件记录数为空"和"导入文件不存在"。
- off：表示导入时不区分"导入文件记录数为空"和"导入文件不存在"。
**默认值：**off
**设置方式：** 该参数属于SUSET类型参数，请参见[表1](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0752.html#ZH-CN_TOPIC_0000002793787853__zh-cn_topic_0059777490_t91a6f212010f4503b24d7943aed6d846)中对应设置方法进行设置。
**设置建议** **：**推荐使用默认值。
**设置不当的风险与影响：**请在充分理解参数含义，并经过测试验证后进行修改。
![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
raise_errors_if_no_files参数只在分布式GDS工具使用场景有意义。
#### gds_debug_mod
**参数说明：**为了增强对Gauss Data Service（以下简称GDS）相关问题的分析定位能力，可以通过此参数选择是否开启GDS的debug功能。参数开启后，将在集群节点对应的日志中输出GDS每次收发的包裹类型、命令交互的对端以及其他交互相关的细节信息，方便记录Gaussdb端状态机的状态跳转，以及目前所处的状态信息。
**参数类型：**布尔型
**参数单位：**无
**取值范围** **：**
- on：表示开启GDS的debug功能。
- off：表示不开启GDS的debug功能。
**默认值：**off
**设置方式：** 该参数属于USERSET类型参数，请参见[表1](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0752.html#ZH-CN_TOPIC_0000002793787853__zh-cn_topic_0059777490_t91a6f212010f4503b24d7943aed6d846)中对应设置方法进行设置。
**设置建议** **：**建议仅在定位GDS问题时开启。
**设置不当的风险与影响：**此参数打开会输出额外日志，增加日志I/O开销，进而影响性能和日志的信息有效性。
 #### safe_data_path
**参数说明：**设置copy、load data、本地节点类型的外表以及非初始用户的高级包进行文件读写操作时的路径限制。对相关路径实行白名单管理，仅允许对白名单路径下的文件进行读写操作。
**参数类型：**字符串
**参数单位：**无
**取值范围：**合法目录路径，需要小于4096个字符。
**默认值：**"copydir_default,copydir_logical_decode"
**设置方式：** 该参数属于SIGHUP类型参数，请参见[表1](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0752.html#ZH-CN_TOPIC_0000002793787853__zh-cn_topic_0059777490_t91a6f212010f4503b24d7943aed6d846)中对应设置方法进行设置。
**设置建议**：尽量控制safe_data_path路径覆盖有限范围，不要设置过大的路径范围。
**设置不当的风险与影响：**将safe_data_path设置为空或将safe_data_path路径范围设置过大时，可能导致恶意用户访问到服务器上的敏感文件。
![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
- 如果safe_data_path目录下存在软链接文件，则会按软链接实际指向的文件路径进行处理，实际路径如果不在safe_data_path下会报错处理。
- 如果safe_data_path目录下存在硬链接文件，则可以正常使用。为安全起见，请谨慎使用硬链接文件，切勿在safe_data_path目录下创建指向目录以外的硬链接文件，并确保safe_data_path目录权限最小化。
- 将safe_data_path参数设置为空，表示不开启白名单校验，用作前向兼容，请在评估风险和影响后谨慎进行设置。
- safe_data_path参数取值中，多个不同的路径间需要使用","进行分隔，且分隔符间不包含空格和制表符等空白字符。
- 参数默认取值中的copydir_default为占位的表示方式，表示白名单中支持使用的默认路径；实际表示的路径为$GAUSSLOG/gs_copy_data；当路径不存在时，可以通过手动执行一次"COPY table_name FROM 'file_name'"或"COPY table_name TO 'file_name'"命令进行创建，或者在对应目录下通过mkdir命令进行创建；在开启白名单功能时，不推荐用户将此参数进行删除。
- 参数默认取值中的copydir_logical_decode为逻辑解码中需要使用到的路径，禁止将其删除，否则可能会对相关功能造成影响。
- 修改safe_data_path参数时，请以","分隔的方式对参数取值进行追加写，禁止对默认值中的路径进行删除。
 
#### enable_copy_server_files
**参数说明：**是否开启copy服务器端文件的权限。
**参数类型：**布尔型
**参数单位：**无
**取值范围：**
- on：表示开启copy服务端文件的权限，允许具有SYSADMIN权限的用户或继承了内置角色gs_role_copy_files权限的用户执行COPY FROM FILENAME或COPY TO FILENAME命令。
- off：表示不开启copy服务端文件的权限，只允许初始用户执行COPY FROM FILENAME或COPY TO FILENAME命令。
**默认值：**off
**设置方式：** 该参数属于SIGHUP类型参数，请参见[表1](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0752.html#ZH-CN_TOPIC_0000002793787853__zh-cn_topic_0059777490_t91a6f212010f4503b24d7943aed6d846)中对应设置方法进行设置。
**设置建议** **：** 仅在需要copy服务端文件时打开，打开后建议同步设置[safe_data_path]。
**设置不当的风险与影响：** 打开该参数后，如果[safe_data_path]设置路径范围过大，可能导致恶意用户访问到服务器上的敏感文件。
#### support_binary_copy_version
**参数说明：**使用COPY TO的BINARY模式导出数据时，是否包含当前数据库服务端的编码信息。
**参数类型** **：**字符串
**参数单位：**无
**取值范围：**""、"header_encoding"。
表1兼容性配置项 
| **兼容性配置项**         | **兼容性行为控制**                                     |
|:---|:---|
| "header_encoding" | 使用COPY TO的BINARY模式导出数据时，二进制文件头中包含当前数据库服务端的编码信息。 |
| ""                | 做前向兼容处理时配置，以原二进制格式进行导出。                        |
   
**默认值："**header_encoding"
**设置方式：** 该参数属于USERSET类型参数，请参见[表1](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0752.html#ZH-CN_TOPIC_0000002793787853__zh-cn_topic_0059777490_t91a6f212010f4503b24d7943aed6d846)中对应设置方法进行设置。
**设置建议：**无特殊情况时建议配置为默认取值，仅做前向兼容时需另行配置为空。
**设置不当的风险与影响：**设置为空字符串时，导出结果中不包含服务端编码信息，在需要编码信息的场景下，需要用户自行查询并记录。
#### copy_special_character_version
**参数说明：**控制使用COPY导入导出数据时对非法编码的字符处理的相关表现。
**参数类型** **：**字符串
**参数单位：**无
**取值范围：**""、"no_error"、"per_byte"。
表2兼容性配置项 
| **兼容性配置项** | **兼容性行为控制**                                                                                                                                                |
|:---|:---|
| "no_error"  | 使用COPY导入数据文件时，当文件编码与服务端编码相同时，对数据文件中不满足编码信息的数据进行容错处理，不报错，并直接按照原编码插入表中。                                                                                     |
| "per_byte"  | 使用COPY导出文本格式的数据文件时，对文件编码为GBK或ZHS16GBK文件的处理方式。 设置"per_byte"后，在导出数据时一次导出一个字节数据，否则一次导出两个字节数据（GBK编码下，一个字符占两个字节）。 |
| ""         | 参数默认配置，不影响任何功能使用，做前向兼容处理。即COPY存在非法编码时报错。                                                                                                                    |
   
**默认值：**""
**设置方式：** 该参数属于USERSET类型参数，请参见[表1](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0752.html#ZH-CN_TOPIC_0000002793787853__zh-cn_topic_0059777490_t91a6f212010f4503b24d7943aed6d846)中对应设置方法进行设置。使用gsql连接数据库，使用set方式设置时不区分大小写，使用gs_guc设置时仅能设置小写。
**设置建议：**推荐使用默认值。
**设置不当的风险与影响：**请在充分理解参数含义，并经过测试验证后进行修改。
![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
- 为保证导入表中数据的合法性，COPY中需要对数据编码的合法性进行校验。当开启此参数后，会屏蔽非法校验操作并导致字段内出现非法字符，请酌情考虑开启此参数。
- 当前屏蔽数据编码校验仅在服务端编码与数据编码保持一致时生效，即copy_special_character_version值为"no_error"时，数据库服务端编码须与数据文件编码保持一致，否则会报错；未指定数据编码时，数据编码默认为客户端编码。
- 二进制模式下，copy_special_character_version值为"no_error"时，仅对TEXT、CHAR、VARCHAR、NVARCHAR2、CLOB类型的字段生效。
- 此参数仅在UTF-8、GB18030、GB18030_2022、ZHS16GBK、LATIN1字符集数据库下使用生效。
- 客户端编码与服务端编码都为GBK或ZHS16GBK时，当数据库内存在非法编码的数据时，如果不设置copy_special_character_version值为"per_byte"，导出的数据文件中可能会存在预期外的数据。
- 设置copy_special_character_version值为"no_error"的优先级高于COPY内COMPATIBLE_ILLEGAL_CHARS参数。
 
#### enable_log_copy_illegal_chars
**参数说明：**使用COPY导入导出数据时，遇到非法编码的字符时，是否向数据库运行日志中写入记录。
**参数类型** **：**布尔型
**参数单位：**无
**取值范围：**on、off。
表3兼容性配置项 
| **兼容性配置项** | **兼容性行为控制**                           |
|:---|:---|
| on          | 每出现一行包括非法编码字符的数据，都会向数据库运行日志中写入一条记录。 |
| off         | 不向数据库运行日志中写入非法编码字符相关记录。            |
   
**默认值：**on
**设置方式：** 该参数属于USERSET类型参数，请参见[表1](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0752.html#ZH-CN_TOPIC_0000002793787853__zh-cn_topic_0059777490_t91a6f212010f4503b24d7943aed6d846)中对应设置方法进行设置。
**设置建议：**无特殊情况时建议配置为默认值，仅对数据库性能及磁盘带宽有要求时设置为off。
**设置不当的风险与影响：**设置为off时将不会在运行日志中写入非法编码字符相关记录，影响可定位能力。
#### batch_insert_index_types
**参数说明：**在特定场景下执行批量插入时，是否开启批量插入索引性能优化。
**参数类型** **：**字符串
**参数单位：**无
**取值范围：**"rcr_ubtree"、""。
表4兼容性配置项 
| **兼容性配置项**   | **兼容性行为控制**                         |
|:---|:---|
| "rcr_ubtree" | rcr_ubtree类别的索引在批量插入时开启批量插入索引特性。 |
| ""           | 任何类别的索引不开启批量插入索引特性。                |
   
**默认值：**""。
**设置方式：** 该参数属于USERSET类型参数，请参见[表1](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0752.html#ZH-CN_TOPIC_0000002793787853__zh-cn_topic_0059777490_t91a6f212010f4503b24d7943aed6d846)中对应设置方法进行设置。
**设置建议：**建议配置为默认值，如果出现性能大幅下降则将本项目设为""。
![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
当以下任何一个场景满足所有的约束条件时，打开GUC参数可以提升批量插入索引性能：
场景1：使用JDBC连接数据库，通过java的批量插入数据接口executeBatch进行批量插入索引；
场景2：执行语句insert into t1 select \* from t2，其中t1和t2表schema相同，t1表包含索引，此语句支持在t1表上批量插入索引；必须要开启stream计划（enable_fast_query_shipping参数被设置成off），并在批量插入表数据的前提（使用explain verbose命令查看）下才会批量插入索引；
场景3：执行语句copy t1 from 'file.csv' delimiter ',' csv header，其中t1和file.csv文件中的schema相同，t1表包含索引，此语句支持在t1表上批量插入索引。
约束1：插入的索引类型为ubtree RCR索引；
约束2：插入数据不递增（这种情况下原来的机制会利用缓存，无性能提升）；
约束3：enable_stream_operator参数被设置成on；
约束4：不是SMP的批量索引插入。
**设置不当的风险与影响：**请在充分理解参数含义，并经过测试验证后进行修改。
#### a_format_enable_copy_empty_lobs
**参数说明：**在Oracle兼容模式下，执行COPY FROM批量插入时，是否允许通过空串输入向BLOB及CLOB类型中插入空字符串。
**参数类型** **：**布尔型
**参数单位：**无
**取值范围：**on、off。
表5兼容性配置项 
| **兼容性配置项** | **兼容性行为控制**                                                                                                                                                  |
|:---|:---|
| on         | Oracle兼容模式下，允许通过空串输入向CLOB及BLOB类型中插入空串。 比如将1,"",3插入到表中后，第二个字段的结果为空，但是无法通过where col2 is null进行过滤，且字段的长度为0。      |
| off      | Oracle兼容模式下，允许通过空串输入向CLOB及BLOB类型中插入空串。空串会被转换为NULL进行存储。 比如将1,"",3插入到表中后，第二个字段的结果为NULL，可以通过where col2 is null进行过滤。 |
   
**默认值：**on
**设置方式：** 该参数属于USERSET类型参数，请参见[表1](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0752.html#ZH-CN_TOPIC_0000002793787853__zh-cn_topic_0059777490_t91a6f212010f4503b24d7943aed6d846)中对应设置方法进行设置。
**设置建议：**建议配置为默认值，如果需要前向兼容再设置为off。
![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
- 关于空串输入与空值输入： 在COPY的CSV格式下，1,,3表示空值输入，1,"",3表示空串输入。参数开启时，前者的第二个字段会被插入为NULL，后者的第二个字段会被插入为空串；参数关闭时，前者和后者的第二个字段都会被插入为NULL。
  

- 对于新安装部署的数据库，参数默认取值为on；对于升级上来的数据库，出于前向兼容考虑，参数默认取值为off。
 
**设置不当的风险与影响：**请在充分理解参数含义，并经过测试验证后进行修改。
#### enable_copy_case_sensitive
**参数说明：**使用gs_loader导入数据及COPY...TRANSFORM()导入数据需要表达式处理时，遇到大写字符列或包含特殊的列名时，是否保留列名的大小写敏感。
**参数类型** **：**布尔型
**参数单位：**无
**取值范围：**on、off。
**默认值：**off
**设置方式：** 该参数属于USERSET类型参数，请参见[表1](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0752.html#ZH-CN_TOPIC_0000002793787853__zh-cn_topic_0059777490_t91a6f212010f4503b24d7943aed6d846)中对应设置方法进行设置。
**设置建议：**建议配置为默认值，在表列中存在大写列名、特殊字符列名且需要在导入过程使用表达式处理相关列时，设置为on。
![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
- 在gs_loader控制文件中，对大写字符列、包含特殊字符的列进行表达式处理，会默认转为小写匹配表中的列，若存在大写列名、特殊字符列名，通过开启参数enable_copy_case_sensitive=on后，在控制文件中通过双引号""转义标识保留列名，参考示例如下： LOAD DATA
  CHARACTERSET UTF8
  truncate into table "IMP_COLNAME_TEST"
  FIELDS TERMINATED BY ","
  (
  id integer external,
  name char(32),
  "Column_Mixed" "TRIM(:""Column_Mixed"")",
  "Col With Space" "TRIM(:""Col With Space"")",
  "COL_UPPER" "TRIM(:""COL_UPPER"")",
  "Col""With""Quote" "TRIM(:""Col""""With""""Quote"")",
  )
  

- 在COPY...TRANSFORM()导入数据需要表达式处理时，使用单引号"标识表达式中的列名，参考示例如下： COPY "IMP_COLNAME_TEST" ( id, name, "Column_Mixed","Col With Space", "COL_UPPER", "Col""With""Quote", con, col_lower )
  FROM 'case.csv'
  TRANSFORM("Column_Mixed" AS TRIM(:"Column_Mixed"),"Col With Space" AS TRIM(:"Col With Space"),"COL_UPPER" AS TRIM(:"COL_UPPER"),"Col""With""Quote" AS TRIM(:"Col""With""Quote")) ;
  
 
**设置不当的风险与影响：**默认off时对表达式中的列名大小写不敏感，统一转义为小写处理，若实际列名为大写字段可能出现导入报错。设置为on时，则以表达式中的列名执行表达式处理后，进行导入操作。