概要

COPY table [(column [, ...])] FROM {'file' | STDIN}
     [ [WITH] 
       [BINARY]
       [OIDS]
       [HEADER]
       [DELIMITER [ AS ] 'delimiter']
       [NULL [ AS ] 'null string']
       [ESCAPE [ AS ] 'escape' | 'OFF']
       [NEWLINE [ AS ] 'LF' | 'CR' | 'CRLF']
       [CSV [QUOTE [ AS ] 'quote'] 
            [FORCE NOT NULL column [, ...]]
       [FILL MISSING FIELDS]
       [[LOG ERRORS]  
       SEGMENT REJECT LIMIT count [ROWS | PERCENT] ]

COPY {table [(column [, ...])] | (query)} TO {'file' | STDOUT}
      [ [WITH] 
        [ON SEGMENT]
        [BINARY]
        [OIDS]
        [HEADER]
        [DELIMITER [ AS ] 'delimiter']
        [NULL [ AS ] 'null string']
        [ESCAPE [ AS ] 'escape' | 'OFF']
        [CSV [QUOTE [ AS ] 'quote'] 
             [FORCE QUOTE column [, ...]] ]
      [IGNORE EXTERNAL PARTITIONS ]

描述

如果指定了一个列列表，COPY 将只把指定列的数据复制到文件或者从文件复制数据到指定列。如果表中有列不在列列表中， COPY FROM 将会为那些列插入默认值。

带一个文件名的COPY 指示 Greenplum数据库服务器直接从一个文件读取 或者写入到一个文件。 该主机必须可访问该文件，并且必须从主主机的角度指定该名称。

当 COPY 和 ON SEGMENT 选项一起被使用时， COPY TO 导致Segment创建面向Segment的个体文件，这些文件保留在Segment主机上。ON SEGMENT 的文件参数是用字符串文字<SEGID> (必须) 并使用 绝对路径或 <SEG_DATA_DIR> 字符串文字。 当运行 COPY 操作时，Segment的ID和Segment数据目录的路径被替换为字符串文字值。

当指定STDIN或STDOUT时，通过客户端和主机之间的连接传输数据。 STDOUT不能 与ON SEGMENT选项一起使用。

如果使用了SEGMENT REJECT LIMIT ，则 COPY FROM 操作将在单行错误隔离模式下运行。在此版本中，单行错误隔离模式仅适用于具有格式错误的输入文件中的行 - 例如，额外或缺少属性，错误数据类型的属性或无效的客户端编码序列。诸如违反了 NOT NULL, CHECK, 或UNIQUE 约束的约束错误仍将以 'all-or-nothing' 输入模式进行处理。用户可以指定可接受的错误行数（以每个Segment为单位），之后整个COPY FROM 操作将被终止， 并且不再加载任何行。 错误行的计数以每个Segment而不是整个加载操作为基础。如果未达到每Segment的拒绝限制，则将加载不包含错误的所有行，并丢弃任何错误行。要保留错误行进一步检查， 请指定LOG ERRORS子句以补货错误日志信息。 错误信息和行存储在Greenplum数据库中。

COPY count

NOTICE: Rejected count badly formatted rows.

参数

table

一个现有表的名称（可以是方案限定的）。

column

可选的要被复制的列列表。如果没有指定列列表，则该表的所有列都会被复制。

当以文本格式复制时，默认为一列数据类型 bytea 最高可达 256MB.

query

一个SELECT 或 VALUES 其结果将被复制。请注意，查询需要括号。

file

输入或者输出文件的路径名。

。

STDIN

指定输入来自客户端应用。

STDOUT

指定输出会去到客户端应用。

ON SEGMENT

拷贝表数据以创建单独的面向Segment的文件，这些文件保留在Segment主机上。 COPY FROM该ON SEGMENT 目前不支持输出。COPY TO STDOUT 不能用于 ON SEGMENT。<SEG_DATA_DIR> 和 <SEGID> 字符串文字用于 ON SEGMENT, 具有以下语法：

COPY table TO '<SEG_DATA_DIR>/gpdumpname<SEGID>_suffix' ON SEGMENT; 

镜像Segment不会将其数据拷贝到Segment文件中。

<SEG_DATA_DIR>

表示 ON SEGMENT拷贝的Segment数据目录的完整路径的字符串文字。支架是用于指定路径的字符串文字的一部分。 COPY运行时，用字符串文字替换段路径。 (可选。 可以用绝对路径 代替使用 <SEG_DATA_DIR> 字符串文字。)

<SEGID>

表示复制 ON SEGMENT时要复制的Segment的内容ID号的字符串文字。 <SEGID> 是 ON SEGMENT 选项的必需部分。 支架是用于指定路径的字符串文字的一部分。 COPY 运行时， COPY 将使用内容ID替换字符串文字。

BINARY

使所有数据以二进制格式存储或读取，而不是文本。用户不能指定 DELIMITER, NULL,或CSV 二进制模式下的选项。参阅Binary Format.

当以二进制格式复制时，一行数据最多可达1GB。

OIDS

指定复制每行的OID。（如果为没有OID的表指定了OIDS，或者在复制查询的情况下，则会引发错误。）

分隔符

单个ASCII字符，用于分隔文件每行（行）中的列。默认是文本模式下的制表符，逗号在 CSV 模式。

空字符串

表示空值的字符串。 文本模式中的默认值为\N (反斜杠-N) ， CSV模式中不含引号的空值。 在不想将空值与空字符串区分开的情况下，即使在文本模式下，也可能更喜欢空字符串。 当使用 COPY FROM时，与字符串 匹配的任何数据项将被转储为空值，因为用户应该确保使用与 COPY TO中使用的字符串相同。

escape

指定用于C转义序列的单个字符(如 \n,\t,\100, 等) 和引用可能被视为行或列分隔符的数据字符。确保选择在实际列数据中的任何地方都不使用的转义字符。默认转义符为\ (反斜杠)用于文本文件或 " (双引号) 用于 CSV 文件, 但是可以指定任何其他字符来表示转义。还可以通过指定值 OFF' 作为转义值。这对于诸如Web日志数据之类的数据非常有用，该数据具有许多嵌入式反斜杠，这些反斜杠不是要转义的。

NEWLINE

指定数据文件中使用的换行符 — LF（换行，0x0A）、CR（回车，0x0D）或者CRLF（回车加换行，0x0D 0x0A）。如果未指定，Greenplum数据库的Segment将通过查看其接收的第一行数据并使用遇到的第一个换行符来检测换行类型。

CSV

选择逗号分隔值（CSV）模式。参阅CSV 格式。

HEADER

指定一个文件包含一个标题行和文件中每列的名称。在输出时，第一行包含表中的列名，在输入时，第一行将被忽略。

引用

以CSV模式指定引用字符。默认是双引号。

FORCE QUOTE

在CSV COPY TO模式下，强制引用用于每个指定列中的所有 非NULL 值。 NULL 值输出从不引用。

FORCE NOT NULL

在CSV COPY FROM 模式下，处理每一个指定的列，就好像它被引用一样， 因此不是NULL 值。对于 CSV模式默认的字符串(两个分割符之间不存在)，这会导致将值作为零长度字符串计算。

FILL MISSING FIELDS

在TEXT 和CSV 中的 COPY FROM中，指定FILL MISSING FIELDS时，当一行数据 在行或行的末尾缺少数据字段时，将丢失尾字段值设置为 NULL (而不是报告错误)。 空行，具有 NOT NULL在TEXT和CSV中的COPY FROM中，指定FILL MISSING FIELDS时，当一行数据在行或行的末尾缺少数据字段时，将丢失尾字段值设置为NULL（而不是报告错误）。 空行，具有NOT NULL约束的字段和行上的尾随分隔符仍然会报告错误。

LOG ERRORS

这是一个可选子句，可以在 SEGMENT REJECT LIMIT 之前捕获有关格式错误的行的错误日志信息。

错误日志信息在内部存储，并使用数据库内置SQL函数 gp_read_error_log()访问。

这是一个可选的子句，可以在SEGMENT REJECT LIMIT子句之前捕获有关格式错误的行的错误日志信息。错误日志信息在内部存储， 并使用Greenplum数据库内置SQL函数gp_read_error_log（）访问。有关错误日志信息和内置函数的信息，参阅注释 以查看和管理错误日志信息。

SEGMENT REJECT LIMIT count [ROWS | PERCENT]

在单行模式下运行COPY FROM 操作。 如果输入行具有格式错误，则它们将被丢弃，前提是在加载操作期间在任何Greenplum数据库Segment实例上未达到拒绝限制计数。拒绝限制计数可以指定为行数（默认值）或总行数百分比（1-100）。 如果PERCENT被使用，每个Segment只有在处理参数 gp_reject_percent_threshold 所指定的行数之后才开始计算行百分比。 gp_reject_percent_threshold默认值为300行。 诸如违反 NOT NULL， CHECK, 或 UNIQUE的约束错误仍将以 'all-or-nothing' 输入模式 进行处理。如果达到限制，如果没有达到限制，所有好的行将被加载，任何错误将被丢弃。

注意： Greenplum数据库限制了可能包含格式错误的初始行数 SEGMENT REJECT LIMIT 不是首先被触发或没有被指定。 如果前1000行被拒绝，COPY 操作停止并回滚。

可以使用Greenplum Database服务器配置参数更改初始拒绝行数的限制 gp_initial_bad_row_limit。 。有关参数的信息，参阅 服务器配置参数

IGNORE EXTERNAL PARTITIONS

从分区表复制数据时，数据不会从作为外部表的叶子分区复制。当不复制数据时，会将消息添加到日志文件中。

如果未指定此子句，并且Greenplum数据库尝试从作为外部表的叶子分区复制数据，则会返回错误。

有关指定从作为外部表的叶子分区复制数据的SQL查询的信息，请参阅下一节“注释”。

注解

COPY 只能与表一起使用，而不能与外部表或视图一起使用。 但是，用户可以写COPY (SELECT * FROM viewname) TO ...

COPY (SELECT * from my_sales ) TO stdout

该BINARY 关键字将所有数据存储/读取为二进制格式而不是文本。它比正常的文本模式要快一点，但二进制格式的文件在机器架构和Greenplum数据库版本之间的移植性更低。 另外， 用户不能运行COPY FROM 在单行错误隔离模式下，如果数据是二进制格式。

用户必须对其值由COPY TO 读取的表具有 SELECT权限，并在 COPY FROM插入的值上插入特权。

在COPY 命令中 a在COPY命令中命名的文件由数据库服务器直接读取或写入，而不是由客户端应用程序读取或写入。 因此，它们必须驻留在Greenplum数据库主机主机上或可访问，而不是客户端。 它们必须由Greenplum数据库系统用户（服务器运行的用户ID）而不是客户机可访问和可读写。 COPY 命名文件只允许数据库超级用户使用，因为它允许读取或写入服务器具有访问权限的任何文件。

COPY FROM将调用目标表上的任何触发器和检查约束。 但是，它不会调用重写规则。 请注意，在此版本中，不对单行错误隔离模式评估对约束的违规。

COPY 的输入输出受 DateStyle影响。为了确保 对可能使用非默认 DateStyle 设置的其他Greenplum数据库安装的可移植性，在使用 COPY TO之前， 应将DateStyle设置为ISO。

在文本模式下从文件复制XML数据时，服务器配置参数 xmloption 影响复制的XML数据的验证。 如果值为 content (默认)， XML数据被验证为XML内容片段。如果参数值为 document,XML数据被验证为XML文档。如果XML数据无效， COPY 返回错误。

默认情况下， COPY在第一个错误时停止运行。 在COPY TO的情况下，这不应该导致问题 但是目标表已经在COPY FROM中接受了较早的行。这些行将不可见或可访问，但他们仍占用磁盘空间，如果故障发生在大的 COPY FROM 操作中这可能会相当大量的浪费磁盘空间。用户可能希望 VACUUM 来恢复浪费的空间。 另一个选择时使用单行错误隔离模式来过滤错误行，同时仍然加载好的行。

当用户指定 LOG ERRORS 子句时，Greenplum数据库捕获读取外部表数据时发生的错误。用户可以查看和管理捕获的错误日志数据。

• 使用内置的SQL函数 gp_read_error_log('table_name')。需要在 table_name 上有SELECT特权。 此示例 显示使用 COPY命令加载到表ext_expenses 中的数据错误日志信息：

  SELECT * from gp_read_error_log('ext_expenses');

  有关错误日志格式的信息，请参阅“Greenplum数据库管理员指南”中的在错误日志中查看不正确的行。

  该函数返回FALSE 如果 table_name 表不存在。

• 如果指定的表存在错误日志数据，新的错误日志数据将附加到现有的错误日志数据。错误日志信息不会复制到镜像Segment。
• 使用内置的SQL函数 gp_truncate_error_log('table_name') 删除 table_name中的错误日志数据。它需要表所有者权限此示例删除将数据移动到表中时捕获的错误日志信息 ext_expenses:

  SELECT gp_truncate_error_log('ext_expenses'); 

  函数返回FALSE if table_name 表不存在。

  指定 * 通配符删除当前数据库中现有表的错误日志信息。指定字符串 *.*删除所有数据库错误日志信息，包括由于以前的数据库问题而未被删除的错误日志信息。如果 * 没被指定， 则需要数据库所有者权限。如果*.* 被指定，需要操作系统超级用户权限。

当不是超级用户的Greenplum数据库用户运行时 COPY 命令时， 命令可以由资源队列控制。必须配置资源队列 ACTIVE_STATEMENTS参数，指定分配给该队列的角色可以执行的查询数量的最大限制。Greenplum数据库不会将消耗值或内存值应用于COPY命令， 只有消耗或内存限制的资源队列不影响运行COPY 命令。

有关资源队列的信息，请参阅 Greenplum数据库管理员指南中的“具有资源队列的工作负载管理”。

文件格式

文件格式支持 COPY。

percentage sign = % | vertical bar = *| | backslash = \

示例

使用垂直条（|）作为字段分隔符将表复制到客户端：

COPY country TO STDOUT WITH DELIMITER '|';

从文件中复制数据到country 表中:

COPY country FROM '/home/usr1/sql/country_data';

复制到名称以'A'开头的国家/地区的文件:

COPY (SELECT * FROM country WHERE country_name LIKE 'A%') TO 
'/home/usr1/sql/a_list_countries.copy';

将数据从文件复制到sales 表使用单行错误隔离模式和日志错误：

COPY sales FROM '/home/usr1/sql/sales_data' LOG ERRORS 
   SEGMENT REJECT LIMIT 10 ROWS;

要拷贝Segment数据供以后使用，使用 ON SEGMENT 语句。 使用 ON SEGMENT 语句的形式为:

COPY table TO '<SEG_DATA_DIR>/gpdumpname<SEGID>_suffix' ON SEGMENT;

该<SEGID>是必须的。 但是，用户可以替换绝对路径 <SEG_DATA_DIR>字符串文字在路径中。

当用户传递字符串文字 <SEG_DATA_DIR> 和 <SEGID> 到 COPY, COPY 将在运行操作时填写适当的值。

contentid | dbid | file segment location 
    0     |  1   |/home/usr1/data1/gpsegdir0

    0     |  3   | /home/usr1/data_mirror1/gpsegdir0 

    1     |  4   | /home/usr1/data2/gpsegdir1

    1     |  2   | /home/usr1/data_mirror2/gpsegdir1 

COPY mytable TO '<SEG_DATA_DIR>/gpbackup<SEGID>.txt' ON SEGMENT;

/home/usr1/data1/gpsegdir0/gpbackup0.txt
/home/usr1/data2/gpsegdir1/gpbackup1.txt

第一列中的内容ID是插入到文件路径中的标识符 (例 如， gpsegdir0/gpbackup0.txt above) 文件是在Segment主机上创建的，而不是在主服务器上，因为它们将在标准中COPY 操作。 使用时，不会为镜像Segment创建任何数据文件 ON SEGMENT复制。

COPY mytable TO '/tmp/gpdir/gpbackup_<SEGID>.txt' ON SEGMENT;

兼容性

在SQL标准中没有COPY 语句。

另见

CREATE EXTERNAL TABLE