本文导读

展开导读

文档首页/ 云数据库 GaussDB/ 开发指南（分布式_V2.0-8.x）/ 配置运行参数/ GUC参数说明/ 数据并行导入导出

数据并行导入导出

更新时间：2025-05-29 GMT+08:00

查看PDF

GaussDB提供了并行导入导出功能，以快速、高效地完成大量数据导入导出。介绍GaussDB并行导入导出的相关参数。

raise_errors_if_no_files

参数说明：设置导入时是否区分“导入文件记录数为空”和“导入文件不存在”。该参数开启时，“导入文件不存在”的时候，GaussDB将抛出“文件不存在”的错误。

参数类型：布尔型

参数单位：无

取值范围：

on：表示导入时区分“导入文件记录数为空”和“导入文件不存在”。
off：表示导入时不区分“导入文件记录数为空”和“导入文件不存在”。

默认值：off

设置方式：该参数属于SUSET类型参数，请参见表1中对应设置方法进行设置。

设置建议：推荐使用默认值。

设置不当的风险与影响：请在充分理解参数含义，并经过测试验证后进行修改。

说明：

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中对应设置方法进行设置。

设置建议：建议仅在定位GDS问题时开启。

设置不当的风险与影响：此参数打开会输出额外日志，增加日志I/O开销，进而影响性能和日志的信息有效性。

safe_data_path

参数说明：设置初始用户以外的路径前缀限制，目前包括copy和高级包路径限制。

参数类型：字符串

参数单位：无

取值范围：合法目录路径，需要小于4096个字符。

默认值：""

设置方式：该参数属于SIGHUP类型参数，请参见表1中对应设置方法进行设置。

设置建议：尽量控制safe_data_path路径覆盖有限范围，不要设置过大的路径范围。

设置不当的风险与影响：当enable_copy_server_files打开，并且safe_data_path路径范围设置过大时，可能导致恶意用户访问到服务器上的敏感文件。

说明：

如果safe_data_path目录下存在软链接文件，则会按软链接实际指向的文件路径进行处理，实际路径如果不在safe_data_path下会报错处理。
如果safe_data_path目录下存在硬链接文件，则可以正常使用。为安全起见，请谨慎使用硬链接文件，切勿在safe_data_path目录下创建指向目录以外的硬链接文件，并确保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中对应设置方法进行设置。

设置建议：仅在需要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中对应设置方法进行设置。

设置建议：无特殊情况时建议配置为默认取值，仅做前向兼容时需另行配置为空。

设置不当的风险与影响：设置为空字符串时，导出结果中不包含服务端编码信息，在需要编码信息的场景下，需要用户自行查询并记录。

copy_special_character_version

参数说明：控制使用COPY导入导出数据时对非法编码的字符处理的相关表现。

参数类型：字符串

参数单位：无

取值范围：""、"no_error"、"per_byte"。

表2 兼容性配置项
兼容性配置项	兼容性行为控制
"no_error"	使用COPY导入数据文件时，当文件编码与服务端编码相同时，对数据文件中不满足编码信息的数据进行容错处理，不报错，并直接按照原编码插入表中。
"per_byte"	使用COPY导出文本格式的数据文件时，对文件编码为GBK或ZHS16GBK文件的处理方式。设置per_byte后，在导出数据时一次导出一个字节数据，否则一次导出两个字节数据（GBK编码下，一个字符占两个字节）。
""	参数默认配置，不影响任何功能使用，做前向兼容处理。即COPY存在非法编码时报错。

默认值：""

设置方式：该参数属于USERSET类型参数，请参见表1中对应设置方法进行设置。使用gsql连接数据库，使用set方式设置时不区分大小写，使用gs_guc设置时仅能设置小写。

设置建议：推荐使用默认值。

设置不当的风险与影响：请在充分理解参数含义，并经过测试验证后进行修改。

说明：

为保证导入表中数据的合法性，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

参数说明：使用gs_loader导入数据及COPY导入导出数据时，遇到非法编码的字符时，是否向数据库运行日志中写入记录。

参数类型：布尔型

参数单位：无

取值范围：on、off。

表3 兼容性配置项
兼容性配置项	兼容性行为控制
on	每出现一行包括非法编码字符的数据，都会向数据库运行日志中写入一条记录。
off	不向数据库运行日志中写入非法编码字符相关记录。

默认值：on

设置方式：该参数属于USERSET类型参数，请参见表1中对应设置方法进行设置。

设置建议：无特殊情况时建议配置为默认值，仅对数据库性能及磁盘带宽有要求时设置为off。

设置不当的风险与影响：设置为off时将不会在运行日志中写入非法编码字符相关记录，影响可定位能力。

a_format_enable_copy_empty_lobs

参数说明：ORA兼容模式下，执行COPY FROM批量插入时，是否允许通过空字符串输入向BLOB及CLOB类型中插入空字符串。

参数类型：布尔型

参数单位：无

取值范围：on、off。

表4 兼容性配置项
兼容性配置项	兼容性行为控制
on	ORA兼容模式下，允许通过空字符串输入向CLOB及BLOB类型中插入空字符串。比如将1,"",3插入到表中，第二个字段的结果为空，但是无法通过WHERE col2 IS null进行过滤，且字段的长度为0。
off	ORA兼容模式下，允许通过空字符串输入向CLOB及BLOB类型中插入空字符串。空字符串会被转换为NULL进行存储。比如将1,"",3插入到表中，第二个字段的结果为NULL，可以通过WHERE col2 IS null进行过滤。

默认值：on

设置方式：该参数属于USERSET类型参数，请参见表1中对应设置方法进行设置。

设置建议：建议配置为默认值，如果需要前向兼容再设置为off。

说明：

关于空字符串输入与空值输入：
在COPY的CSV格式下，1,,3表示空值输入，1,"",3表示空字符串输入。参数开启时，前者的第二个字段会被插入为NULL，后者的第二个字段会被插入为空字符串；参数关闭时，前者和后者的第二个字段都会被插入为NULL。

对于新安装部署的数据库，参数默认取值为on；对于升级更新后的数据库，为了保证数据库的前向兼容性，参数默认取值为off。

设置不当的风险与影响：请在充分理解参数含义，并经过测试验证后进行修改。

父主题： GUC参数说明

上一篇：异步I/O

下一篇：预写式日志

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消

数据并行导入导出

raise_errors_if_no_files

gds_debug_mod

safe_data_path

enable_copy_server_files

support_binary_copy_version

copy_special_character_version

enable_log_copy_illegal_chars

a_format_enable_copy_empty_lobs

意见反馈

文档内容是否对您有帮助？

文档反馈