参数说明
-
query
其结果将被拷贝。
取值范围:一个必须用圆括弧包围的SELECT或VALUES命令。
-
table_name
表的名称(可以有模式修饰)。
取值范围:已存在的表名。
-
column_name
可选的待拷贝字段列表。
取值范围:如果没有声明字段列表,将使用所有字段。
-
STDIN
声明输入是来自标准输入。
-
STDOUT
声明输出打印到标准输出。
-
FIXED
打开字段固定长度模式。在字段固定长度模式下,不能声明DELIMITER、NULL、CSV选项。指定FIXED类型后,不能再通过option或copy_option指定BINARY、CSV、TEXT等类型。
说明: 定长格式定义如下:
- 每条记录的每个字段长度相同。
- 长度不足的字段以空格填充,数字类型字段左对齐,字符字段右对齐。
- 字段和字段之间没有分隔符。
-
[USING] DELIMITER 'delimiters'
在文件中分隔各个字段的字符串,分隔符最大长度不超过10个字节。
取值范围:不允许包含\.abcdefghijklmnopqrstuvwxyz0123456789中的任何一个字符。
缺省值:在文本模式下,缺省是水平制表符,在CSV模式下是一个逗号。
-
WITHOUT ESCAPING
在TEXT格式中,不对'\'和后面的字符进行转义。
取值范围:仅支持TEXT格式。
-
LOG ERRORS
若指定,则开启对于COPY FROM语句中数据类型错误的容错机制。
取值范围:仅支持导入(即COPY FROM)时指定。
说明:
此容错选项的使用限制如下:
- 此容错机制仅捕捉COPY FROM过程中数据库主节点上数据解析过程中相关的数据类型错误(DATA_EXCEPTION)。
- COPY已有的容错选项(如IGNORE_EXTRA_DATA)开启时,对应类型的错误会按照已有的方式处理而不会报出异常,因此错误表也不会有相应数据。
-
LOG ERRORS DATA
LOG ERRORS DATA和LOG ERRORS的区别:
-
LOG ERRORS DATA会填充容错表的rawrecord字段。
-
只有supper权限的用户才能使用LOG ERRORS DATA参数选项。
注意: 使用LOG ERRORS DATA时,若错误内容过于复杂可能存在写入容错表失败的风险,导致任务失败。
-
-
REJECT LIMIT 'imit'
与LOG ERROR选项共同使用,对COPY FROM的容错机制设置数值上限,一旦此COPY FROM语句错误数据超过选项指定条数,则会按照原有机制报错。
取值范围:正整数(1-INTMAX),'unlimited'(无最大值限制)
缺省值:若未指定LOG ERRORS,则会报错;若指定LOG ERRORS,则默认为0。
说明: 如上述LOG ERRORS中描述的容错机制,REJECT LIMIT的计数也是按照执行COPY FROM的数据库主节点上遇到的解析错误数量计算,而不是数据库节点的错误数量。
-
FORMATTER
在固定长度模式中,定义每一个字段在数据文件中的位置。按照column(offset,length)格式定义每一列在数据文件中的位置。
取值范围:
- offset取值不能小于0,以字节为单位。
- length取值不能小于0,以字节为单位。
所有列的总长度和不能大于1GB。
文件中没有出现的列默认以空值代替。
-
OPTION { option_name ' value ' }
用于指定兼容外表的各类参数。
-
FORMAT
数据源文件的格式。
取值范围:CSV、TEXT、FIXED、BINARY。
- CSV格式的文件,可以有效处理数据列中的换行符,但对一些特殊字符处理有欠缺。
- TEXT格式的文件,可以有效处理一些特殊字符,但无法正确处理数据列中的换行符。
- FIXED格式的文件,适用于每条数据的数据列都比较固定的数据,长度不足的列会添加空格补齐,过长的列则会自动截断。
- BINARY形式的选项会使得所有的数据被存储/读作二进制格式而不是文本。 这比TEXT和CSV格式的要快一些,但是一个BINARY格式文件可移植性比较差。
缺省值:TEXT
-
DELIMITER
指定数据文件行数据的字段分隔符。
说明:
-
分隔符不能是\r和\n。
-
分隔符不能和null参数相同,CSV格式数据的分隔符不能和quote参数相同。
-
TEXT格式数据的分隔符不能包含:小写字母、数字和特殊字符.\。
-
数据文件中单行数据长度需<1GB,如果分隔符较长且数据列较多的情况下,会影响导出有效数据的长度。
-
分隔符推荐使用多字符和不可见字符。多字符例如'$^&';不可见字符例如0x07、0x08、0x1b等。
取值范围:支持多字符分隔符,但分隔符不能超过10个字节。
缺省值:
- TEXT格式的默认分隔符是水平制表符(tab)。
- CSV格式的默认分隔符为“,”。
- FIXED格式没有分隔符。
-
-
NULL
用来指定数据文件中空值的表示。
取值范围:
- null值不能是\r和\n,最大为100个字符。
- null值不能和分隔符、quote参数相同。
缺省值:
- CSV格式下默认值是一个没有引号的空字符串。
- 在TEXT格式下默认值是\N。
-
HEADER
指定导出数据文件是否包含标题行,标题行一般用来描述表中每个字段的信息。header只能用于CSV、FIXED格式的文件中。
在导入数据时,如果header选项为on,则数据文本第一行会被识别为标题行,会忽略此行。如果header为off,而数据文件中第一行会被识别为数据。
在导出数据时,如果header选项为on,且未指定fileheader,则将把表的列名信息导出到文件的第一行;如果指定了fileheader,则将把fileheader文件的第一行导出到最终输出文件的第一行。如果header为off,则导出数据文件不包含标题行。
取值范围:true/on、false/off。
缺省值:false
-
QUOTE
CSV格式文件下的引号字符。
缺省值:双引号
说明:
- quote参数不能和分隔符、null参数相同。
- quote参数只能是单字节的字符。
- 推荐不可见字符作为quote,例如0x07、0x08、0x1b等。 例如quote e'\x22' :使用ASCII编码为16进制22的字符。
-
ESCAPE
CSV格式下,用来指定逃逸字符,逃逸字符只能指定为单字节字符。
缺省值:双引号。当与quote值相同时,会被替换为'\0'。
-
EOL 'newline_character'
指定导入导出数据文件换行符样式。
取值范围:支持多字符换行符,但换行符不能超过10个字节。常见的换行符,如\r、\n、\r\n(设成0x0D、0x0A、0x0D0A效果是相同的),其他字符或字符串,如$、#。
说明:
-
EOL参数只能用于TEXT格式的导入导出,不支持CSV格式和FIXED格式导入。为了兼容原有EOL参数,仍然支持导出CSV格式和FIXED格式时指定EOL参数为0x0D或0x0D0A。
-
EOL参数不能和分隔符、null参数相同。
-
EOL参数不能包含:.abcdefghijklmnopqrstuvwxyz0123456789。
-
-
FORCE_QUOTE { ( column_name [, …] ) | * }
在CSV COPY TO模式下,强制在每个声明的字段周围对所有非NULL值都使用引号包围。NULL输出不会被引号包围。
取值范围:已存在的字段。
-
FORCE_NOT_NULL ( column_name [, …] )
此函数指定的列将不会把输入匹配(识别)为 null 字符串。null 值字符串将被默认为空字符串,即长度为零的字符串而不是 null,即使它们没有用引号引起来。 此选项仅允许在“COPY FROM”语句中,并且仅在指定为 CSV 格式时被允许使用。
取值范围:已存在的字段。
-
ENCODING
指定数据文件的编码格式名称,缺省为当前数据库编码格式。
-
IGNORE_EXTRA_DATA
若数据源文件比外表定义列数多,是否会忽略对多出的列。该参数只在数据导入过程中使用。
取值范围:true/on、false/off。
-
参数为true/on,若数据源文件比外表定义列数多,则忽略行尾多出来的列。
-
参数为false/off,若数据源文件比外表定义列数多,会显示如下错误信息。
extra data after last expected column
缺省值:false。
须知:
如果行尾换行符丢失,使两行变成一行时,设置此参数为true将导致后一行数据被忽略掉。
-
-
COMPATIBLE_ILLEGAL_CHARS
导入非法字符容错参数。此语法仅对COPY FROM导入有效。
取值范围:true/on、false/off。
- 参数为true/on,则导入时遇到非法字符进行容错处理,非法字符转换后入库,不报错,不中断导入。
- 参数为false/off,导入时遇到非法字符进行报错,中断导入。
缺省值:false/off
说明:
导入非法字符容错规则如下:
(1)对于'\0',容错后转换为空格;
(2)对于其他非法字符,容错后转换为问号;
(3)若compatible_illegal_chars为true/on标识导入时对于非法字符进行容错处理,则若NULL、DELIMITER、QUOTE、ESCAPE设置为空格或问号则会通过如“illegal chars conversion may confuse COPY escape 0x20”等报错信息提示用户修改可能引起混淆的参数以避免导入错误。
-
FILL_MISSING_FIELDS
当数据加载时,若数据源文件中一行的最后一个字段缺失的处理方式。
取值范围:true/on、false/off。
缺省值:false/off
-
DATE_FORMAT
导入对于DATE类型指定格式。此参数不支持BINARY格式,会报“cannot specify bulkload compatibility options in BINARY mode”错误信息。此参数仅对COPY FROM导入有效。
取值范围:合法DATE格式。可参考时间和日期处理函数和操作符。
说明:
对于DATE类型内建为TIMESTAMP类型的数据库,在导入的时候,若需指定格式,可以参考下面的timestamp_format参数。
-
TIME_FORMAT
导入对于TIME类型指定格式。此参数不支持BINARY格式,会报“cannot specify bulkload compatibility options in BINARY mode”错误信息。此参数仅对COPY FROM导入有效。
取值范围:合法TIME格式,不支持时区。可参考时间和日期处理函数和操作符。
-
TIMESTAMP_FORMAT
导入对于TIMESTAMP类型指定格式。此参数不支持BINARY格式,会报“cannot specify bulkload compatibility options in BINARY mode”错误信息。此参数仅对COPY FROM导入有效。
取值范围:合法TIMESTAMP格式,不支持时区。可参考时间和日期处理函数和操作符。
-
SMALLDATETIME_FORMAT
导入对于SMALLDATETIME类型指定格式。此参数不支持BINARY格式,会报“cannot specify bulkload compatibility options in BINARY mode”错误信息。此参数仅对COPY FROM导入有效。
取值范围:合法SMALLDATETIME格式。可参考[时间和日期处理函数和操作符](时间和日期处理函数和操作符.md)。
-
-
COPY_OPTION { option_name ' value ' }
用于指定COPY原生的各类参数。
-
NULL null_string
用来指定数据文件中空值的表示。
须知:
在使用COPY FROM的时候,任何匹配这个字符串的字符串将被存储为NULL值,所以应该确保指定的字符串和COPY TO相同。
取值范围:
- null值不能是\r和\n,最大为100个字符。
- null值不能和分隔符、quote参数相同。
缺省值:
- 在TEXT格式下默认值是\N。
- CSV格式下默认值是一个没有引号的空字符串。
-
HEADER
指定导出数据文件是否包含标题行,标题行一般用来描述表中每个字段的信息。header只能用于CSV、FIXED格式的文件中。
在导入数据时,如果header选项为on,则数据文本第一行会被识别为标题行,会忽略此行。如果header为off,而数据文件中第一行会被识别为数据。
在导出数据时,如果header选项为on,且未指定fileheader,则将把表的列名信息导出到文件的第一行;如果指定了fileheader,则将把fileheader文件的第一行导出到最终输出文件的第一行。如果header为off,则导出数据文件不包含标题行。
-
FILEHEADER
导出数据时用于定义标题行的文件,一般用来描述每一列的数据信息。
须知:
-
仅在header为on或true的情况下有效。
-
fileheader指定的是绝对路径。
-
该文件只能包含一行标题信息,并以换行符结尾,多余的行将被丢弃(标题信息不能包含换行符)。
-
该文件包括换行符在内长度不超过1M。
-
-
FREEZE
将COPY加载的数据行设置为已经被frozen,就像这些数据行执行过VACUUM FREEZE。
这是一个初始数据加载的性能选项。仅当以下三个条件同时满足时,数据行会被frozen:
- 在同一事务中create或truncate这张表之后执行COPY。
- 当前事务中没有打开的游标。
- 当前事务中没有原有的快照。
说明:
- COPY完成后,所有其他会话将会立刻看到这些数据。但是这违反了MVCC可见性的一般原则,用户应当了解这样会导致潜在的风险。
- 当条件不满足时,FREEZE选项将会被忽略而不会报错。
-
FORCE NOT NULL column_name [, …]
在CSV COPY FROM模式下,指定的字段不为空。若输入为空,则将视为长度为0的字符串。
取值范围:已存在的字段。
-
FORCE NULL column_name [, …]
在CSV COPY FROM模式下,将指定的字段表示空值的字符串设置为NULL,包括加了引号的空值字符串。
取值范围:已存在的字段。
-
FORCE QUOTE { column_name [, …] | * }
在CSV COPY TO模式下,强制在每个声明的字段周围对所有非NULL值都使用引号包围。NULL输出不会被引号包围。
取值范围:已存在的字段。
-
BINARY
使用二进制格式存储和读取,而不是以文本的方式。在二进制模式下,不能声明DELIMITER、NULL、CSV选项。指定BINARY类型后,不能再通过option或copy_option指定CSV、FIXED、TEXT等类型。
-
CSV
打开逗号分隔变量(CSV)模式。指定CSV类型后,不能再通过option或copy_option指定BINARY、FIXED、TEXT等类型。
-
QUOTE [AS] 'quote_character'
CSV格式文件下的引号字符。
缺省值:双引号。
说明:
- quote参数不能和分隔符、null参数相同。
- quote参数只能是单字节的字符。
- 推荐不可见字符作为quote,例如0x07、0x08、0x1b等。 例如quote e'\x22' :使用ASCII编码为16进制22的字符。
-
ESCAPE [AS] 'escape_character'
CSV格式下,用来指定逃逸字符,逃逸字符只能指定为单字节字符。 默认值为双引号。当与quote值相同时,会被替换为'\\0'。
-
EOL 'newline_character'
指定导入导出数据文件换行符样式。
取值范围:支持多字符换行符,但换行符不能超过10个字节。常见的换行符,如\r、\n、\r\n(设成0x0D、0x0A、0x0D0A效果是相同的),其他字符或字符串,如$、#。
说明:
- EOL参数只能用于TEXT格式的导入导出,不支持CSV格式和FIXED格式。为了兼容原有EOL参数,仍然支持导出CSV格式和FIXED格式时指定EOL参数为0x0D或0x0D0A。
- EOL参数不能和分隔符、null参数相同。
- EOL参数不能包含:.abcdefghijklmnopqrstuvwxyz0123456789。
-
ENCODING 'encoding_name'
指定文件编码格式名称。
取值范围:有效的编码格式。
缺省值:当前编码格式。
-
IGNORE_EXTRA_DATA
指定当数据源文件比外表定义列数多时,忽略行尾多出来的列。该参数只在数据导入过程中使用。
若不使用该参数,在数据源文件比外表定义列数多,会显示如下错误信息。
extra data after last expected column
-
COMPATIBLE_ILLEGAL_CHARS
指定导入时对非法字符进行容错处理,非法字符转换后入库。不报错,不中断导入。此参数不支持BINARY格式,会报“cannot specify bulkload compatibility options in BINARY mode”错误信息。此参数仅对COPY FROM导入有效。
若不使用该参数,导入时遇到非法字符进行报错,中断导入。
说明:
导入非法字符容错规则如下: (1)对于'\0',容错后转换为空格; (2)对于其他非法字符,容错后转换为问号; (3)若compatible_illegal_chars为true/on标识,导入时对于非法字符进行容错处理,则若NULL、DELIMITER、QUOTE、ESCAPE设置为空格或问号则会通过如“illegal chars conversion may confuse COPY escape 0x20”等报错信息提示用户修改可能引起混淆的参数以避免导入错误。
-
FILL_MISSING_FIELDS
当数据加载时,若数据源文件中一行的最后一个字段缺失的处理方式。
取值范围:true/on、false/off。
缺省值:false/off。
须知:
目前COPY指定此Option实际不会生效,即不会有相应的容错处理效果(不生效)。需要额外注意的是,打开此选项会导致解析器在数据库主节点数据解析阶段(即COPY错误表容错的涵盖范围)忽略此数据问题,而到数据库节点重新报错,从而使得COPY错误表(打开LOG ERRORS REJECT LIMIT)在此选项打开的情况下无法成功捕获这类少列的数据异常。因此请不要指定此选项。
-
DATE_FORMAT 'date_format_string'
导入对于DATE类型指定格式。此参数不支持BINARY格式,会报“cannot specify bulkload compatibility options in BINARY mode”错误信息。此参数仅对COPY FROM导入有效。
取值范围:合法DATE格式。可参考时间和日期处理函数和操作符。
说明:
对于DATE类型内建为TIMESTAMP类型的数据库,在导入的时候,若需指定格式,可以参考下面的timestamp_format参数。
-
TIME_FORMAT 'time_format_string'
导入对于TIME类型指定格式。此参数不支持BINARY格式,会报“cannot specify bulkload compatibility options in BINARY mode”错误信息。此参数仅对COPY FROM导入有效。
取值范围:合法TIME格式,不支持时区。可参考时间和日期处理函数和操作符。
-
TIMESTAMP_FORMAT 'timestamp_format_string'
导入对于TIMESTAMP类型指定格式。此参数不支持BINARY格式,会报“cannot specify bulkload compatibility options in BINARY mode”错误信息。此参数仅对COPY FROM导入有效。
取值范围:合法TIMESTAMP格式,不支持时区。可参考时间和日期处理函数和操作符。
-
SMALLDATETIME_FORMAT 'smalldatetime_format_string'
导入对于SMALLDATETIME类型指定格式。此参数不支持BINARY格式,会报“cannot specify bulkload compatibility options in BINARY mode”错误信息。此参数仅对COPY FROM导入有效。
取值范围:合法SMALLDATETIME格式。可参考时间和日期处理函数和操作符。
-
TRANSFORM ( { column_name [ data_type ] [ AS transform_expr ] } [, …] )
指定表中各个列的转换表达式;其中data_type指定该列在表达式参数中的数据类型;transform_expr为目标表达式,返回与表中目标列数据类型一致的结果值,表达式可参考表达式。
COPY FROM能够识别的特殊反斜杠序列如下所示。
- \b:反斜杠 (ASCII 8)
- \f:换页(ASCII 12)
- \n:换行符 (ASCII 10)
- \r:回车符 (ASCII 13)
- \t:水平制表符 (ASCII 9)
- \v:垂直制表符 (ASCII 11)
- \digits:反斜杠后面跟着一到三个八进制数,表示ASCII值为该数的字符。
- \xdigits:反斜杠x后面跟着一个或两个十六进制位声明指定数值编码的字符。
-