参数

COPY 参数及其描述分为以下部分：

• 目标选项

• 列选项

• 输入选项

• 处理选项

• 解析器特定选项

目标选项

以下选项适用于目标表及其列：

LABEL

将标签分配到语句，以便您可以在分析和调试时识别它。

[database.]schema

数据库和架构。默认架构为 public。如果指定一个数据库，它必须是当前数据库。

在 CREATE EXTERNAL TABLE 或 CREATE FLEX EXTERNAL TABLE 语句中使用时，COPY 将忽略 schema-name。

target-table

用于加载新数据的目标列式表或 Flex 表。Vertica 将数据从架构表加载到包含列的全部投影中。

column-as-expression

用于计算目标列值的表达式，不可以是复杂类型。例如：

=> COPY t(year AS TO_CHAR(k, 'YYYY')) FROM 'myfile.dat'

当加载到目标数据库时，使用该选项来转换数据。

有关详细信息，请参阅在加载期间转换数据。

列

限制加载至表中一个或多个指定列。如果未指定列，COPY 将默认加载所有列。

将向从列列表中忽略的表列分配其 DEFAULT 或 SET USING 值（如有）；否则，COPY 将插入 NULL。

如果将 column 参数留空以加载表中的所有列，则可以使用可选参数 COLUMN OPTION 来为特定列指定解析选项。

数据文件必须包含与 COPY 命令列列表中数量相同的列。

COLUMN OPTION

为表列列表中声明的一个或多个列指定加载元数据。例如，可以指定一个具有自己的 DELIMITER、ENCLOSED BY 或 NULL AS 等表达式的列。不必在 COLUMN OPTION 列表中显式指定每个列名称，但是指定的每一列必须对应表列列表中的列。

列选项

根据选项的指定方式，以下 COPY 选项可以对特定列或所有列进行限定。某些解析器特定选项也可以应用于特定列或所有列。有关这两种模式的详细信息，请参阅全局选项和特定于列的选项。

ENFORCELENGTH

如果指定，COPY 将拒绝 CHAR、VARCHAR、BINARY 和 VARBINARY 类型的数据行，或集合中这些类型的元素（如果集合大于声明的大小）。

默认情况下，COPY 会截断这些数据类型的违反约束的行以及集合中这些类型的元素，但不会拒绝这些行。有关更多详细信息，请参阅处理混乱数据。

如果集合不适合其所有元素，COPY 会拒绝行，但不会截断。不会减少元素的数量。如果每个元素各自都在限制范围内，但元素数量导致集合超过列的最大大小，则可能会发生这种情况。

FILLER datatype

读取但不复制输入列的数据。使用填充内容列来忽略在表中没有列的输入列。还可以使用填充内容列来转换数据（请参阅示例和在加载期间转换数据）。填充内容列不可以是复杂类型。

FORMAT 'format'

输入格式，为以下之一：

• 八进制

• 十六进制

• 比特流

请参阅二进制（原生）数据了解更多关于这些格式的信息。

加载日期/时间列时，使用 FORMAT 会显著提升加载性能。COPY 与 TO_DATE 函数支持相同的格式。请参阅用于日期/时间格式化的模板模式。

如果指定了无效格式的字符串，COPY 操作将返回错误。

NULL [AS]

该字符串表示空值。默认为一个空字符串 ('')。可以将 null 值指定为 E'\000' 至 E'\177'（包含）范围内的任何 ASCII 值。不能对 DELIMITER 和 NULL 选项使用相同的字符。有关详细信息，请参阅分隔数据。

输入选项

以下选项可用于指定源数据：

LOCAL

在客户端系统上加载数据文件，而不是在群集主机上。LOCAL 可以限定 STDIN 和 path-to-data 参数。有关详细信息，请参阅COPY LOCAL。

限制： 对 CREATE EXTERNAL TABLE AS COPY

STDIN 无效

从客户端读取标准输入而非文件。STDIN 只接受一个输入源。要加载多个输入源，请使用 path-to-data。

用户必须具有表的 INSERT 权限以及架构的 USAGE 权限。

限制： 对 CREATE EXTERNAL TABLE AS COPY 无效

path-to-data

指定包含数据的文件的绝对路径，可来自多个输入源。

• 如果文件存储在 HDFS 中，则 path-to-data webhdfs 是架构中的 URI，通常为 [[s]web]hdfs://[nameservice]/path。请参阅HDFS 文件系统。

• 如果文件存储在 S3 存储桶中，则 path-to-data 是格式为 s3://bucket/path 的 URI。请参阅S3 对象存储。

• 如果文件存储在 Google Cloud Storage 中，则 path-to-data 是格式为 gs://bucket/path 的 URI。请参阅Google Cloud Storage (GCS) 对象存储。

• 如果文件存储在 Azure Blob 存储中，则 path-to-data 是格式为 azb://account/container/path 的 URI。请参阅Azure Blob 存储对象存储。

• 如果文件位于本地 Linux 文件系统或 NFS 装载上，则 path-to-data 为本地绝对文件路径。

path-to-data 可以选择包含通配符以和多个文件匹配。文件必须可供本地客户端或 COPY 语句运行的主机访问。COPY 会跳过文件列表中的空文件。若文件列表包含目录，则会导致查询失败。请参阅指定加载数据的位置。在 Linux Manual Page for Glob (7) 中指定了通配符支持的模式，对于 ADO.net 平台，则通过 NET Directory.getFiles 方法指定。

可使用变量来构建 使用加载脚本 中描述的路径名。

如果 path-to-data 解析为本地文件系统上的存储位置，且调用 COPY 的用户为非超级用户，则将应用以下要求：

• 存储位置使用 CREATE LOCATION...USAGE USER 进行创建。

• 用户必须已经具有文件存储位置的 READ 权限。

此外，如果用户具有权限但不是超级用户，并且从该存储位置调用 COPY，Vertica 会确保符号链接不会导致未经授权的访问。

PARTITION COLUMNS column[,...]

其值在目录结构中而不是在数据中指定的列。此选项在路径包含形式为 colname=value 的目录名称时有效，例如：

/data/created=2016-01-01/*.dat
/data/created=2016-01-02/*.dat
/data/created=2016-01-03/*.dat

值通过目录名称的 value 部分进行解析。如果不能强制转换为列数据类型，该值将被拒绝。如果该值缺失，COPY 会将其加载为 null。

以下示例将这些日期与数据文件中的其他列一起加载到表列中：

=> CREATE EXTERNAL TABLE records
    (id int, name varchar(50), created date)
   AS COPY FROM 'webhdfs:///path/*/*'
   PARTITION COLUMNS created;

有关详细信息，请参阅分区文件路径。

ON nodename

指定要复制的数据所驻留的节点以及应解析加载文件的节点。如果忽略 nodename，输入文件的位置默认为启动程序节点。使用 nodename 从 COPY 启动程序节点以外的节点复制和解析加载文件。

注意

nodename 对 STDIN 和 LOCAL 无效。

ON (nodeset)

指定一组要在其上执行加载的节点。相同数据必须可供在所有指定节点上加载。nodeset 是括号中节点名称的逗号分隔列表。例如：

=> COPY t FROM 'file1.txt' ON (v_vmart_node0001, v_vmart_node0002);

Vertica 将加载分摊到所有指定节点。如果同时指定了 ERROR TOLERANCE 或 REJECTMAX，Vertica 会改为选择单个节点来执行加载。

如果数据在所有节点上都可用，则通常会使用 ON ANY NODE，这是从 HDFS 和云对象存储加载所使用的默认值。但是，可以使用 ON nodeset 在并发加载之间手动平衡加载。

ON ANY NODE

指定要加载的源文件在所有节点上都可用，这样 COPY 可以打开文件并从群集的任一节点解析。对于 Eon 模式数据库，COPY 将使用与启动程序相同的子群集中的节点。

当心

所有节点上的文件必须相同。如果其中两个节点上的文件不同，则将返回不正确或不完整的结果，但不显示错误或警告。

如果文件足够大，可以进行分摊，Vertica 会尝试在多个节点之间分摊加载。如果指定了 ERROR TOLERANCE 或 REJECTMAX，Vertica 将选择单个节点。

可使用通配符或 glob（如 *.dat）并结合 ON ANY NODE 子句加载多个输入文件。如果使用 glob，COPY 会将文件列表分配至所有群集节点并分散工作负载。

ON ANY NODE 对于 STDIN 和 LOCAL 无效。STDIN 只能使用客户端主机，LOCAL 表示客户端节点。

ON ANY NODE 是从 Linux 以外的所有路径（HDFS 和云对象存储）加载时使用的默认值。

ON EACH NODE

从每个节点的指定路径加载数据。当每个节点上的数据文件不同，且您想要加载所有这些文件时，请使用此选项。如果路径在所有节点上都无效，则 COPY 会加载有效路径并生成警告。如果路径是共享位置，则 COPY 仅在 ON ANY NODE 上加载一次。

compression

输入压缩类型，为以下之一：

• UNCOMPRESSED（默认）

• BZIP

• GZIP

• LZO

• ZSTD

输入文件可以是任何格式。如果使用通配符，所有的限定输入文件必须是相同的格式。要加载不同的文件格式，则指定具体的格式类型。

以下要求和限制适用：

• 使用串联的 BZIP 或 GZIP 文件时，确认所有的源文件在串联之前使用记录终止符终止。

• 串联的 BZIP 和 GZIP 文件不支持 NATIVE（二进制）和 NATIVE VARCHAR 格式。

• LZO 文件假定使用 lzop 进行压缩。Vertica 支持以下 lzop 实参：

  • --no-checksum / -F

  • --crc32

  • --adler32

  • --no-name / -n

  • --name / -N

  • --no-mode

  • --no-time

  • --fast

  • --best

  • 编号的压缩级别

• BZIP、GZIP、ZSTD 和 LZO 压缩不能与 ORC 格式结合使用。

VERTICA

请参阅COPY FROM VERTICA。

[WITH] UDL-clause[...]

指定一个或多个用户定义的加载函数、一个源和（可选）一个或多个筛选器和一个解析器，如下所示：

SOURCE source( [arg=value[,...] ]
[ FILTER filter( [arg=value[,...] ] ) ]...
[ PARSER parser( [arg=value[,...] ] ) ]

要为列表使用 Flex 表解析器，请使用 PARSER 参数，后跟 Flex 表解析器实参。有关支持的 Flex 表解析器，请参阅将数据批量加载到 Flex 表中。

处理选项

以下选项用于控制 COPY 如何处理不同的突发事件：

ABORT ON ERROR

指定如果有任何行被拒绝，则停止 COPY。语句将被回滚，并且不加载数据。

COLSIZES (integer[,...])

加载固定宽度数据时指定列宽。COPY 要求在使用 FIXEDWIDTH 解析器时指定 COLSIZES。COLSIZES 与整数列表必须与表列列表中所列出的列对应。有关详细信息，请参阅固定宽度格式数据。

ERROR TOLERANCE

指定加载数据时，COPY 在执行过程中独立处理每个源。如果单个源无效，则语句不会回滚。将跳过无效的源，并继续加载。

使用此参数可禁用分摊加载。

限制： 对 ORC 或 Parquet 数据无效

EXCEPTIONS

指定文件名或要写入异常的文件的绝对路径，如下所示：

EXCEPTIONS 'path' [ ON nodename[,...]]

异常描述了每个被拒绝的行被拒绝的原因。每个异常描述了通过 REJECTED DATA 选项指定的文件中的相应记录。

文件将被写入执行加载的一个或多个节点上。如果文件已经存在，其将被覆盖。

要收集某个位置的所有异常，请使用 REJECTED DATA AS TABLE 子句，异常会自动列在表的 rejected_reason 列中。

注意

EXCEPTIONS 与 REJECTED DATA AS TABLE 不兼容。

ON nodename 子句将 nodename 上的现有异常文件移至同一节点上所示的 path。有关详细信息，请参阅保存加载异常 (EXCEPTIONS)。

如果将此参数与 COPY...ON ANY NODE 一起使用，则仍必须为异常文件指定单独的节点，如以下示例中所示：

EXCEPTIONS '/home/ex01.txt' on v_db_node0001,'/home/ex02.txt'
on v_db_node0002,'/home/ex03.txt' on v_db_node0003

如果 path 解析为存储位置，则以下权限适用于非超级用户：

• 必须使用 USER 选项创建存储位置（请参阅 CREATE LOCATION）。

• 用户必须具有文件所在存储位置的 READ 权限，如 GRANT（存储位置）中所述。

REJECTED DATA

指定在何处写入加载失败的每一行。如果指定此参数，则将始终写入由于解析错误而失败的记录。仅当设置了配置参数 CopyFaultTolerantExpressions 时，才会写入由于转换过程中的错误而失败的记录。

此参数的语法为：

REJECTED DATA
{ 'path' [ ON nodename ] [,...] | AS TABLE reject-table }

Vertica 可以将被拒绝的数据写入指定路径或表：

• 'path' [ON nodename]：将被拒绝的行数据复制到执行加载的节点上的指定路径。如果通过 ON nodename 进行限定，Vertica 会将 nodename 上现有的被拒绝的数据文件移至同一节点上的 path。

  path 的值可以是目录，也可以是文件前缀。如果存在多个加载源，会始终将 path 视为目录。如果不存在多个加载源，但 path 以 '/' 结尾，或者如果该名称的目录已经存在，则也会将其视为目录。否则，会将 path 视为文件前缀。

  文件将被写入执行加载的一个或多个节点上。如果文件已经存在，其将被覆盖。

  当将此参数与 LOCAL 结合使用时，输出将写入客户端。

  注意

  请勿使用 ON ANY NODE 限定 path。要收集某个位置所有被拒绝的数据（无论加载如何分布），请使用表。

• AS TABLE reject-table：将被拒绝的行保存到 reject-table。

  注意

  REJECTED DATA AS TABLE 与 EXCEPTIONS 不兼容。

有关这两个选项的详细信息，请参阅处理杂乱的数据。

REJECTMAX integer

加载失败前可以拒绝的逻辑记录的最大数量。有关详细信息，请参阅处理杂乱的数据。

REJECTMAX 禁用分摊加载。

SKIP integer

要在加载文件中跳过的记录的数量。例如，可以使用 SKIP 选项来省略表头信息。

限制： 对 ORC 或 Parquet 数据无效

STREAM NAME

提供 COPY 加载流标识符。使用流名称有助于快速识别特定加载。您在加载语句中提供的 STREAM NAME 值将出现在系统表 LOAD_STREAMS 和 LOAD_SOURCES 的 STREAM_NAME 列中。

无效的流名称包含长度最多为 128 字节的字母数字字符或特殊字符组合。

例如：

=> COPY mytable FROM myfile 
   DELIMITER '|' STREAM NAME 'My stream name';

WITH parser

指定批量加载列式表时要使用的解析器，为以下之一：

• NATIVE

• NATIVE VARCHAR

• FIXEDWIDTH

• ORC

• PARQUET

默认情况下，COPY 在 UTF-8 格式下使用 DELIMITER 解析器，分隔文本输入数据。如果未直接指定 DELIMITER 解析器，则缺少特定解析器将表示使用默认设置。

要为列表使用 Flex 表解析器，请使用 PARSER 参数，后跟 Flex 表解析器实参。有关支持的 Flex 表解析器，请参阅将数据批量加载到 Flex 表中。

加载到 Flex 表时，必须使用兼容的解析器。有关支持的 Flex 表解析器，请参阅将数据批量加载到 Flex 表中。

COPY LOCAL 不支持 NATIVE、NATIVE VARCHAR、ORC 和 PARQUET 解析器。

有关复杂数据类型支持的解析器，请参阅特定解析器的文档。

有关解析器的详细信息，请参阅数据加载中的数据格式。

NO COMMIT

防止 COPY 语句在完成复制数据时自动提交事务。此选项必须是最后一个 COPY 语句参数。

有关详细信息，请参阅使用事务暂存加载。

限制： 对 ORC 或 Parquet 数据无效，将被 CREATE EXTERNAL TABLE AS COPY 忽略

解析器特定选项

以下选项仅在使用特定解析器时适用。

DELIMITED 解析器

DELIMITER

表示一个 ASCII 字符，用于分隔文件中每条记录内的各个列。您可以使用 E'\000' 到 E'\177'（包含）范围内的任何 ASCII 值。不能对 DELIMITER 和 NULL 参数使用相同的字符。有关详细信息，请参阅分隔数据。

默认值： 竖线 ('|')。

ENCLOSED [BY]

设置在要其内封装数据的引号字符，允许分隔字符嵌套在字符串值中。可选择范围包含在 E'\001' 至 E'\177'（包含）的任何 ASCII 值（包括除 NULL 以外的任何 ASCII 字符）：E'\000'）。默认情况下，ENCLOSED BY 没有值，即数据不会被任何类型的引号字符包围。

ESCAPE [AS]

设置转义字符。设置后，转义字符后面的字符将按字面意思解释，而不是解释为特殊字符。您可以使用 E'\001' 至 E'\177'（包含）范围内的任何 ASCII 值来定义转义字符（包括除 NULL 以外的任何 ASCII 字符：E'\000'）。

COPY 语句不会将它读取的数据解释为字符串字面量。它也不遵循与其他 SQL 语句（包括 COPY 参数）相同的转义规则。读入数据时，COPY 仅解释被以下选项定义为特殊值的字符：

• ESCAPE [AS]

• DELIMITER

• ENCLOSED [BY]

• RECORD TERMINATOR

• All COLLECTION 选项

默认值： 反斜线 ('\')。

NO ESCAPE

消除转义字符处理。如果不需要任何转义字符并且想要防止数据中的字符不被解释为转义序列，则使用该选项。

RECORD TERMINATOR

指定表明数据文件记录结束的字面量字符字符串。有关使用此参数的更多信息，请参见 分隔数据。

TRAILING NULLCOLS

指定如果 Vertica 遇到的记录不具有足够数据来匹配表列列表中的列，COPY 将使用 NULL 值插入缺失的列。有关其他信息和示例，请参阅固定宽度格式数据。

COLLECTIONDELIMITER

对于集合类型的列，表示用于分隔每个集合中元素的单个 ASCII 字符。您可以使用 E'\000' 到 E'\177'（包含）范围内的任何 ASCII 值。没有任何 COLLECTION 选项可能具有与任何其他 COLLECTION 选项相同的值。有关详细信息，请参阅分隔数据。

默认值： 逗号 (',')。

COLLECTIONOPEN， COLLECTIONCLOSE

对于集合类型的列，这些选项指示标记集合开头和结尾的字符。在元素列表中的其他地方使用这些字符而不转义它们是错误的。没有任何 COLLECTION 选项可能具有与任何其他 COLLECTION 选项相同的值。

默认值： 方括号（'[' 和 ']'）。

COLLECTIONNULLELEMENT

该字符串表示集合中空元素值。可将一个 null 值指定为在范围包含在 E'\001' 至 E'\177'（包含）的任何 ASCII 值（包括除 NULL 以外的任何 ASCII 值：E'\000'）。没有任何 COLLECTION 选项可能具有与任何其他 COLLECTION 选项相同的值。有关详细信息，请参阅分隔数据。

默认值： 'null'

COLLECTIONENCLOSE

对于集合类型的列，设置在要其内封装单个元素的引号字符，允许分隔字符嵌套在字符串值中。可选择范围包含在 E'\001' 至 E'\177'（包含）的任何 ASCII 值（包括除 NULL 以外的任何 ASCII 字符）：E'\000'）。

没有任何 COLLECTION 选项可能具有与任何其他 COLLECTION 选项相同的值。

默认： 双引号（'"'）

FIXEDWIDTH 解析器

SKIP BYTES integer

要在记录中跳过的总字节数。

TRIM

截取从列中指定的字符数。此选项仅在加载固定宽度数据时可用。您可以在表级别设置列的 TRIM，或将其作为 COLUMN OPTION 参数的一部分。