1    COPY table_name [(column_name [, ...])]
2    FROM {'filename' | PROGRAM 'command' | STDIN}
3    [ [ WITH ] ( option [, ...] ) ]
4    [ ON EXECUTOR ]
5    
6    COPY { table_name [(column_name [, ...])] | (query)}
7         TO {'filename' | PROGRAM 'command' | STDOUT}
8         [ [ WITH ] ( option [, ...] ) ]
9         [ ON EXECUTOR ]
10    ```
11    
12    
13    其中`option`可以是以下之一：
14    
15    ``` sql
16    FORMAT format_name
17    OIDS [ boolean ]
18    FREEZE [ boolean ]
19    DELIMITER 'delimiter_character'
20    NULL 'null string'
21    HEADER [ boolean ]
22    QUOTE 'quote_character'
23    ESCAPE 'escape_character'
24    FORCE_QUOTE { ( column_name [, ...] ) | * }
25    FORCE_NOT_NULL ( column_name [, ...] )
26    ENCODING 'encoding_name'
27    FILL MISSING FIELDS
28    LOG ERRORS [ Executor REJECT LIMIT count [ ROWS | PERCENT ] ]
29    IGNORE EXTERNAL PARTITIONS
30    ```
31
32
33## 描述
34
35`COPY`在PalopgMPP数据库表和标准文件系统文件之间移动数据。 `COPY TO`将表的内容复制到一个文件（如果在`ON EXECUTOR`上复制，则将基于Executor ID复制到多个文件）， 而`COPY FROM`将数据从文件复制到表（将数据追加到表中已有的任何内容）。`COPY TO`还可以复制`SELECT`查询的结果。
36
37    如果指定了列列表，则`COPY`仅将指定列中的数据复制到文件中或从文件复制。 如果表中的任何列不在列列表中，则`COPY FROM`将为这些列插入默认值。
38
39    带有文件名的`COPY`指示PalopgMPP数据库Coordinator节点直接从文件读取或写入文件。该文件必须可供Coordinator节点访问，并且必须从Coordinator节点的角度指定名称。
40
41    当`COPY`与`ON EXECUTOR`子句一起使用时， `ON EXECUTOR`导致Executor创建单独的面向Executor的文件，这些文件保留在Executor节点上。
42
43    `ON EXECUTOR`的`filename`参数采用字符串文字`<dbid>`（必需），并使用绝对路径或`<EXE_DATA_DIR>`字符串文字。
44
45    运行`COPY`操作时，Executor ID和相应数据目录的路径将替换为字符串文字值。
46    
47    使用复制表（`DISTRIBUTED REPLICATED`）作为源的`COPY TO`将创建一个文件，其中包含来自单个Executor实例的行，以便目标文件不包含重复的行。
48    
49    将`COPY TO`与`ON EXECUTOR`子句一起使用，并将复制表作为源，则在包含所有表行的Executor节点上创建目标文件。
50    
51    `ON EXECUTOR`子句允许您将表数据复制到Executor节点上的文件中，以用于诸如在集群之间迁移数据或执行备份之类的操作。可以使用诸如`scfs`之类的工具来恢复由`ON EXECUTOR`子句创建的细分数据，这对于高速数据加载非常有用。
52    
53    
54    注意: 建议仅对专业用户使用`ON EXECUTOR`子句。
55    
56    
57    指定`PROGRAM`时，服务器将执行给定命令并从程序的标准输出中读取或写入程序的标准输入。
58    该命令必须从服务器的角度指定，并且可由`palopg`用户执行。
59    
60    
61    当指定`STDIN`或`STDOUT`时，数据将通过客户端和executor之间的连接进行传输。 `STDIN`和`STDOUT`不能与`ON Executor`子句一起使用。
62    
63    如果使用`Executor REJECT LIMIT`，则`COPY FROM`操作将在单行错误隔离模式下运行。
64    
65    单行错误隔离模式仅适用于输入文件中格式错误的行。例如，多余或缺失的属性，错误的数据类型的属性或无效的客户端编码序列。 约束错误（例如违反`NOT NULL`，`CHECK`或`UNIQUE`约束）仍将在“全有或全无”输入模式下处理。
66    
67    用户可以指定可接受的错误行数（基于每个Executor），之后将终止整个`COPY FROM`操作，并且不会加载任何行。 错误行的计数是按Executor而不是整个加载操作计数的。
68    
69    如果未达到每个Executor拒绝的限制，那么将加载所有不包含错误的行，并丢弃所有错误行。
70    
71    
72    要保留错误行以供进一步检查，请指定`LOG ERRORS`子句以捕获错误日志信息。 错误信息和该行存储在PalopgMPP内部数据库中。
73    
74    
75    **输出**
76    
77    成功完成后，`COPY`命令将返回以下形式的命令标签，其中`count`是复制的行数：
78    
79    ``` sql
80    COPY count
81    ```
82    
83    如果以单行错误隔离模式运行`COPY FROM`命令， 如果由于格式错误而未加载任何行，则将返回以下通知消息，其中`count`是拒绝的行数：
84    
85    ``` sql
86    NOTICE: Rejected count badly formatted rows.
87    ```
88
89
90
91
92## 参数
93
94该SQL命令参数说明见下
95
96    `table_name`  
97    :   现有表的名称（可以由模式指定）。
98    
99    `column_name`  
100    :   要复制的列的可选列表。如果未指定列列表，则将复制表的所有列。
101        当以文本格式复制时，默认情况下，`bytea`类型的列中的一行数据最多可为256MB。
102    
103    `query`  
104    :   `SELECT`或`VALUES`命令，其结果将被复制。 请注意，查询周围需要括号。
105    
106    `filename`  
107    :   输入或输出文件的路径名。 输入文件名可以是绝对路径或相对路径，但输出文件名必须是绝对路径。
108    
109    `PROGRAM 'command'` 
110    :   指定要执行的命令。 在`COPY FROM`中，从命令的标准输出中读取输入，而在`COPY TO`中，将输出写入命令的标准输入中。
111        必须从Coordinator节点系统的角度指定该`command`，并且该命令必须由数据库管理员用户（`palopg`）执行。
112        
113        该`command`由shell程序调用。 将参数传递给shell时，请删除或转义对shell具有特殊含义的任何特殊字符。
114        出于安全原因，最好使用固定的命令字符串，或者至少避免在字符串中传递任何用户输入。
115        当指定`ON Executor`时，该命令必须由PalopgMPP数据库管理员用户（`palopg`）在所有PalopgMPP数据库主Executor节点上可执行。 该命令由每个Executor实例执行。
116        `<EXEID>`在`command`中是必需的。
117    
118    `STDIN`  
119    :   指定输入来自客户端应用程序。 `STDIN`不支持`ON EXECUTOR`子句。
120    
121    `STDOUT`  
122    :   指定将输出发送到客户端应用程序。 `STDOUT`不支持`ON EXECUTOR`子句。
123    
124    `boolean`  
125    :   指定是打开还是关闭所选选项。 您可以写入`TRUE`，`ON`或`1`以启用该选项，而可以写入`FALSE`，`OFF`或`0`以禁用该选项。
126        
127        布尔值也可以省略，在这种情况下，假定为`TRUE`。
128    
129    `FORMAT`  
130    :   选择要读取或写入的数据格式：`text`，`csv`（逗号分隔值）或`binary`。 默认为`text`。
131    
132    `OIDS`  
133    :   指定为每行复制OID。 （如果为没有OID的表指定了OIDS，或者在复制查询的情况下，将引发错误。）
134    
135    `FREEZE`  
136    :   请求复制已冻结的行的数据，就像在运行`VACUUM FREEZE`命令之后一样。 这旨在用作初始数据加载的性能选项。仅当在当前子事务中已创建或截断了要加载的表，没有打开游标并且该事务没有任何较旧的快照时，行才会被冻结。
137        
138        注意，一旦成功加载数据，所有其他会话将立即能够看到数据。 这违反了MVCC可见性的常规规则，指定此选项的用户应注意可能引起的潜在问题。
139    
140    `DELIMITER`  
141    :   指定用于分隔文件每一行（行）中各列的字符。 默认为`text`格式的制表符，`CSV`格式的逗号。 这必须是一个单字节字符。
142        
143        使用`binary`格式时，不允许使用此选项。
144    
145    `NULL`  
146    :   指定表示空值的字符串。 默认值为文本格式`\N`（反斜杠-N），以及`CSV`格式的无引号的空字符串。
147        对于不想将空值与空字符串区分开的情况，甚至可能以`text`格式使用空字符串。使用`binary`格式时，不允许使用此选项。
148        
149        注意: 使用`COPY FROM`时，与该字符串匹配的任何数据项都将存储为空值，因此您应确保使用与`COPY TO`相同的字符串。
150    
151    `HEADER`  
152    :   指定文件包含标题行，其中包含文件中每一列的名称。 输出时，第一行包含表中的列名，输入时，第一行被忽略。
153        
154        仅当使用`CSV`格式时才允许使用此选项。
155    
156    `QUOTE`  
157    :   指定在引用数据值时要使用的引用字符。 默认值为双引号。 这必须是一个单字节字符。 仅当使用`CSV`格式时才允许使用此选项。
158    
159    `ESCAPE`  
160    :   指定应该出现在与`QUOTE`值匹配的数据字符之前的字符。
161        缺省值与`QUOTE`值相同（因此，如果引号字符出现在数据中，则将引号字符加倍）。
162        必须是一个单字节字符。 仅当使用`CSV`格式时才允许使用此选项。
163    
164    `FORCE_QUOTE`  
165    :   强制将引号用于每个指定列中的所有非`NULL`值。 `NULL`输出从不引用。 如果指定`*`，则在所有列中都引用非`NULL`值。
166        仅在`COPY TO`中和使用`CSV`格式时才允许使用此选项。
167    
168    `FORCE_NOT_NULL`  
169    :   不要将指定列的值与空字符串匹配。 在默认情况下，空字符串为空时，这意味着空值将被读取为零长度的字符串，而不是空值，即使没有引号也是如此。 仅在`COPY FROM`中和使用`CSV`格式时才允许使用此选项。
170    
171    `ENCODING`  
172    :   指定文件以`encoding_name`编码。 如果省略此选项，则使用当前的客户端编码。 有关更多详细信息，请参见下面的注释。
173    
174    `ON EXECUTOR`  
175    :   在Executor节点上指定各个Executor数据文件。 每个文件都包含由primary Executor实例管理的表数据。
176        
177        例如，当使用`COPY TO...ON EXECUTOR`命令从表中将数据复制到文件时，该命令会在Executor节点上为主机上的每个Executor实例创建一个文件。
178        
179        每个文件都包含由Executor实例管理的表数据。
180        
181        `COPY`命令不会从镜像实例和Executor数据文件之间复制数据。
182        
183        `ON EXECUTOR`不支持关键字`STDIN`和`STDOUT`。
184    
185        `<EXE_DATA_DIR>`和`<EXEID>`字符串文字用于使用以下语法指定绝对路径和文件名：
186        
187        ``` sql
188        COPY table [TO|FROM] '<EXE_DATA_DIR>/scdumpname<EXEID>_suffix' ON EXECUTOR;
189        ```
190        
191        `<EXE_DATA_DIR>`  
192        :   字符串文字，表示用于`ON EXECUTOR`复制的Executor实例数据目录的绝对路径。尖括号（`<`和`>`）是用于指定路径的字符串文字的一部分。
193            
194            运行`COPY`时，`COPY`用Executor路径替换字符串文字。可以使用绝对路径代替`<EXE_DATA_DIR>`字符串文字。
195        
196        `<EXEID>`  
197        :   字符串文字，表示在复制`ON EXECUTOR`时要复制的Executor实例的content ID号。 当指定`ON Executor`时，`<EXEID>`是文件名的必需部分。 尖括号是用于指定文件名的字符串文字的一部分。
198            
199            使用`COPY TO`，当运行`COPY`命令时， 字符串文字将被Executor实例的content ID替换。
200            
201            使用`COPY FROM`，在文件名中指定Executor实例content ID，然后将该文件放在Executor实例主机上。
202            
203            每个主机上的每个primary Executor实例必须有一个文件。 运行`COPY FROM`命令时，数据从文件复制到Executor实例。
204        
205        当指定了`PROGRAM command`子句时，`command`中需要`<EXEID>`字符串文字，而`<EXE_DATA_DIR>`字符串文字是可选的。
206    
207        对于`COPY FROM...ON EXECUTOR`命令，将数据复制到表中时将检查表分配策略。
208        默认情况下，如果数据行违反表分发策略，则返回错误。
209        您可以使用服务器配置参数`sc_enable_Executor_copy_checking`禁用分发策略检查。
210    
211    `NEWLINE`  
212    :   指定数据文件中使用的换行符 - `LF`（换行，0x0A）， `CR`（回车，0x0D），或`CRLF`（回车加换行，0x0D 0x0A）。
213        
214        如果未指定，Executor将通过查看接收到的第一行数据并使用遇到的第一个换行符类型来检测换行符类型。
215    
216    `CSV`  
217    :   选择逗号分隔值（CSV）模式。 
218    
219    `FILL MISSING FIELDS`  
220    :   在`TEXT`和`CSV`的`COPY FROM` more中， 指定`FILL MISSING FIELDS`会将行尾缺少数据字段的数据行设置为`NULL`（而不是报告错误）。
221        空白行，具有`NOT NULL`约束的字段以及行尾的定界符仍然会报告错误。
222    
223    `LOG ERRORS ` 
224    :   这是一个可选的子句，可以在`Executor REJECT LIMIT`子句之前， 以捕获有关具有格式错误的行的错误日志信息。
225        
226        错误日志信息存储在内部，并可以通过PalopgMPP数据库内置的SQL函数`sc_read_error_log()`进行访问。
227    
228    `Executor REJECT LIMIT count [ROWS | PERCENT] ` 
229    :   在单行错误隔离模式下运行`COPY FROM`操作。
230        
231        如果输入行存在格式错误，只要在加载操作期间未在任何PalopgMPP数据库Executor实例上达到拒绝限制计数，它们将被丢弃。
232        
233        拒绝限制计数可以指定为行数（默认）或总行数的百分比（1-100）。 如果使用`PERCENT`，
234        则只有在处理了参数`sc_reject_percent_threshold`指定的行数之后，
235        
236        每个Executor才开始计算错误行百分比。 `sc_reject_percent_threshold`的默认值为300行。约束错误（例如违反`NOT NULL`，`CHECK`或`UNIQUE`约束）仍将在“全有或全无”输入模式下处理。
237        
238        如果未达到限制，则将加载所有正确的行，并丢弃所有错误行。
239    
240        注意: 如果未先触发或未指定`Executor REJECT LIMIT`，则S数据库会限制可能包含格式错误的初始行数。 如果前1000行被拒绝，则`COPY`操作将停止并回滚。
241    
242    `IGNORE EXTERNAL PARTITIONS ` 
243    :   从分区表复制数据时，不会从外部表的叶子分区复制数据。 不复制数据时，将在日志文件中添加一条消息。如果未指定此子句，并且PalopgMPP数据库尝试从作为外部表的叶子分区中复制数据，则返回错误。
244    
245
246
247
248注解
249:   `COPY`只能与表一起使用，而不能与外部表或视图一起使用。 但是，可以执行`COPY (SELECT * FROM viewname) TO ...`
250
251    当指定`ON EXECUTOR`子句时， `COPY`命令不支持在`COPY TO`命令中指定`SELECT`语句。 例如，不支持此命令。
252    
253    ``` sql
254    COPY (SELECT * FROM testtbl) TO '/tmp/mytst<EXEID>' ON EXECUTOR
255    ```
256    
257    `COPY`仅处理特定名称的表，它不会在子表之间复制数据。 因此，例如`COPY table TO`显示的数据与`SELECT * FROM ONLY table`相同。 但是`COPY (SELECT * FROM table) TO ...`可用于转储继承层次结构中的所有数据。
258    
259    同样，要从具有作为外部表的叶子分区的分区表中复制数据，请使用SQL查询来复制数据。
260    例如，如果表`my_sales`包含带有作为外部表的叶子分区，则此命令`COPY my_sales TO stdout`返回错误。 此命令将数据发送到stdout：
261    
262    `BINARY`关键字使所有数据以二进制格式而不是文本形式存储/读取。
263    它比普通的文本模式要快一些，但是二进制格式的文件在计算机体系结构和PalopgMPP数据库版本之间的移植性较差。
264    另外，如果数据为二进制格式，则不能以单行错误隔离模式运行`COPY FROM`。
265    
266    必须对通过`COPY TO`读取的表具有`SELECT`权限， 并且对于通过`COPY FROM`将值插入其中的表具有插入权限。
267    
268    在命令中列出的列上具有列权限就足够了。
269    
270    `COPY`命令中命名的文件由数据库服务器而不是客户端应用程序直接读取或写入。
271    因此，它们必须位于PalopgMPP数据库Coordinator节点上（而不是客户端）或可被其访问。
272    数据库系统用户（服务器运行时使用的用户ID），而不是客户端，必须可以访问它们并对其进行读写。
273    
274    `COPY`命名文件只允许数据库管理员使用，因为它允许读取或写入服务器有权访问的任何文件。
275    
276    `COPY FROM`将调用任何触发器并检查目标表上的约束。 但是，它不会调用重写规则。
277    
278    `COPY`输入和输出受`DateStyle`影响。
279    为了确保可移植到可能使用非默认`DateStyle`设置的其他PalopgMPP数据库安装，在使用`COPY TO`之前，应将`DateStyle`设置为ISO。
280    
281    避免转储`IntervalStyle`设置为`sql_standard`的数据也是一个好主意，因为对于`IntervalStyle`不同设置的服务器可能会误解负间隔值。
282    
283    输入数据将根据`ENCODING`选项或当前客户端编码进行解释， 而输出数据将以`ENCODING`或当前客户端编码进行编码，
284    即使数据没有通过客户端，而是由服务器直接从文件读取或写入文件 。
285    
286    在文本模式下从文件复制XML数据时，服务器配置参数`xmloption`会影响对复制的XML数据的验证。
287    如果该值为`content`（默认值），则将XML数据验证为XML内容片段。
288    如果参数值为`document`，则将XML数据验证为XML文档。 如果XML数据无效，则`COPY`返回错误。
289    
290    默认情况下，`COPY`在第一个错误时停止操作。 如果是`COPY TO`，这应该不会导致问题，但是目标表已经在`COPY FROM`中接收到了较早的行。 这些行将不可见或不可访问，但仍会占用磁盘空间。 如果故障在大型`COPY FROM`操作中发生，则可能会浪费大量磁盘空间。 您可能希望调用`VACUUM`来恢复浪费的空间。
291    另一种选择是使用单行错误隔离模式来过滤掉错误行，同时仍然加载正确的行。
292    
293    运行`COPY FROM...ON EXECUTOR`命令时，服务器配置参数`sc_enable_Executor_copy_checking`控制在将数据复制到表中时是否检查表分发策略（来自表`DISTRIBUTED`子句）。
294    默认设置为检查分发策略。 如果数据行违反了Executor实例的分配策略，则返回错误。
295    
296    `COPY TO...ON EXECUTOR`命令生成的表数据可用于通过`COPY FROM...ON EXECUTOR`恢复表数据。但是，使用`COPY TO`命令生成文件时，将根据表分发策略来分发恢复到Executor的数据。
297    如果尝试还原表数据并且在运行`COPY FROM...ON Executor`之后更改了表分发策略，则`COPY`命令可能会返回表分发策略错误。
298    
299    
300    注意: 如果运行`COPY FROM...ON EXECUTOR`，并且服务器配置参数`sc_enable_Executor_copy_checking`为`false`，则可能需要手动重新分配表数据。
301    
302    
303    
304    当您指定`LOG ERRORS`子句时，PalopgMPP数据库将捕获读取外部表数据时发生的错误。 您可以查看和管理捕获的错误日志数据。
305    
306    使用内置的SQL函数`sc_read_error_log('table_name')`。
307        
308    要求对`table_name`具有`SELECT`权限。
309    
310    本示例使用`COPY`命令显示加载数据到表`ext_expenses`的错误日志信息：
311        
312    ``` sql
313    SELECT * from sc_read_error_log('ext_expenses');
314    ```
315        
316    如果`table_name`不存在，则该函数返回`FALSE`。
317    
318    如果指定表存在错误日志数据，则新的错误日志数据将附加到现有错误日志数据中。 错误日志信息不会复制到镜像实例。
319    
320    使用内置的SQL函数`sc_truncate_error_log('table_name')`删除`table_name`的错误日志数据。
321    
322    它需要表所有者权限。 本示例删除将数据移入表`ext_expenses`时捕获的错误日志信息：
323        
324    ``` sql
325    SELECT sc_truncate_error_log('ext_expenses');
326    ```
327        
328    如果`table_name`不存在，则该函数返回`FALSE`。
329        
330    指定`*`通配符可删除当前数据库中所有表的错误日志信息。指定字符串`*.*`以删除所有数据库错误日志信息，包括由于先前的数据库问题而未被删除的错误日志信息。
331    
332    如果指定`*`，则需要数据库所有者权限。 如果指定`*.*`，则需要操作系统数据库管理员权限。
333    
334    非数据库管理员只能运行以下类型的`COPY`命令：
335    
336    
337    * 源为`stdin`的`COPY FROM`命令
338    
339    * 目标为`stdout`的`COPY TO`命令
340
341    
342    文件格式
343    :   `COPY`支持的文件格式。
344    
345    
346    文本格式
347    :   使用文本格式时，读取或写入的数据是一个文本文件，每行一行。 行中的列由`delimiter_character`分隔（默认为制表符）。列值本身是由每个属性的数据类型的输出函数生成的字符串，或输入函数可接受的字符串。 使用空字符串代替空列。如果输入文件的任何行包含的列比预期的多或少，则`COPY FROM`将引发错误。如果指定了`OIDS`，则将OID读取或写入为用户数据列之前的第一列。    
348
349        数据文件具有两个保留字符，它们对于`COPY`具有特殊含义：
350        
351        指定的分隔符（默认为制表符），用于分隔数据文件中的字段。UNIX样式的换行符（`\n`或`0x0a`），用于在数据文件中指定新行。
352        
353        强烈建议生成`COPY`数据的应用程序将数据换行转换为UNIX样式的换行， 而不是Windows样式的回车换行（`\r\n`或`0x0a 0x0d`）。
354        
355        如果数据包含这些字符中的任何一个，则必须转义该字符，以便`COPY`将其视为数据而不是字段分隔符或新行。
356        
357        默认情况下，对于文本格式的文件，转义字符是\\（反斜杠），对于csv格式的文件，转义字符是`"`（双引号）。如果要使用其他转义字符，则可以使用`ESCAPE AS`子句来实现。确保选择一个在数据文件中任何地方都没有使用的转义字符作为实际数据值， 也可以通过使用`ESCAPE 'OFF'`来禁用文本格式文件中的转义。
358        
359        例如，假设您有一个包含三列的表，并且想使用`COPY`加载以下三个字段。
360        
361        百分号 = `%`
362        竖线 = `|`
363        反斜杠 = `\`
364        
365        指定的`delimiter_character`为`|`（竖线字符），而您指定的转义字符为`*`（星号）。 数据文件中的格式化行如下所示：
366        
367        ``` sql
368        percentage sign = % | vertical bar = *| | backslash = \
369                        
370        ```
371        
372        请注意，如何使用星号字符（\*）对作为数据一部分的管道字符进行转义。 另请注意，由于我们使用的是替代转义字符，因此我们不需要转义反斜杠。
373        
374        如果以下字符作为列值的一部分出现，则必须在其后加上转义字符：转义字符本身，换行符，回车符和当前定界符。 您可以使用`ESCAPE AS`子句指定其他转义字符。
375
376
377
378        CSV格式
379        :   此格式选项用于导入和导出许多其他程序（例如电子表格）使用的逗号分隔值（CSV）文件格式。它生成并识别常见的CSV转义机制，而不是PalopgMPP数据库标准文本格式使用的转义规则。
380        
381            每个记录中的值由`DELIMITER`字符分隔。 如果值包含定界符，`QUOTE`字符，`ESCAPE`字符（默认情况下为双引号），`NULL`字符串，回车符或换行符，则整个值将以`QUOTE`字符作为前缀和后缀。在特定列中输出非`NULL`值时，也可以使用`FORCE_QUOTE`强制使用引号。
382            
383            CSV格式没有区分`NULL`值和空字符串的标准方法。 PalopgMPP数据库`COPY`通过引用进行处理。输出`NULL`作为`NULL`参数字符串， 并且不加引号，而与`NULL`字符串匹配的非`NULL`值被加引号。
384            
385            例如，使用默认设置，将`NULL`写入未加引号的空字符串，而将空字符串数据值写入双引号（`""`）。 读取值遵循类似的规则。可以使用`FORCE_NOT_NULL`来防止对特定列进行`NULL`输入比较。
386            
387            由于反斜杠不是`CSV`格式的特殊字符，因此`\.`（数据结尾标记）也可能会显示为数据值。为避免任何误解，使用`\.`在行上显示为单独条目的数据值会在输出上自动加引号，并且在输入上（如果加引号）也不会被解释为数据结束标记。如果要加载的文件是由另一个应用程序创建的，该文件具有未加引号的单列并且可能具有`\.`值，则可能需要在输入文件中使用该值。
388            
389            
390            注意: 
391            
392            * 在`CSV`格式中，所有字符均有效。用引号括起来的空格或除`DELIMITER`以外的任何字符都将包含这些字符。
393            
394              如果从空白行填充到固定宽度的CSV行的系统中导入数据，则可能会导致错误。
395            
396              如果出现这种情况，在将数据导入PalopgMPP数据库之前，可能需要预处理CSV文件以删除尾随空白。
397            
398              `CSV`格式将识别并生成带有引用值的CSV文件，这些值包含嵌入式回车符和换行符。 因此，与文本格式的文件相比，文件并非严格限于每行一行
399            
400            
401            
402            * 许多程序会生成奇怪的（有时是错误的）CSV文件，因此文件格式更像是约定俗成的标准文件。因此，您可能会遇到一些无法使用此机制导入的文件，并且`COPY`可能会生成其他程序无法处理的文件。
403
404
405
406
407        二进制格式
408        :   二进制格式选项使所有数据以二进制格式而不是文本形式存储/读取。它比文本和`CSV`格式要快一些，但是二进制格式的文件在计算机体系结构和PalopgMPP数据库版本之间的可移植性较差。
409        同样，二进制格式是非常特定于数据类型的。例如，即使在文本格式下也可以正常工作，但从`smallint`列输出二进制数据并将其读入整数列将不起作用。
410        
411            二进制文件格式由文件头，包含行数据的零个或多个元组和文件尾部组成。 文件头和数据按网络字节序排列。
412        
413            文件头
414            :   文件头由15个字节的固定字段组成，后跟可变长度的头扩展区。固定字段是：
415                
416                签名
417                :   11字节序列`SDCOPY\\n\\377\\r\\n\\0` .注意，零字节是签名的必需部分。（签名旨在方便识别非8位纯净传输所破坏的文件。此签名将通过行尾翻译过滤器，丢失的零字节，丢失的高位或奇偶性更改。）
418                
419                标识字段
420                :   32位整数位掩码，表示文件格式的重要方面。位的编号从0（LSB）到31（MSB）。
421                    
422                    注意，该字段以网络字节序存储（最高有效字节在前），文件格式中使用的所有整数字段也是如此。
423                    
424                    保留位16-31标志关键的文件格式问题；如果读取器发现在此范围内设置了意外的位，则应该中止。保留位0-15标志向后兼容的格式问题；读者只需忽略此范围内设置的任何意外位。
425                    当前仅定义一个标志，其余标志必须为零（如果数据具有OID，则位16为1，否则为0）。
426                
427                文件头扩展区长度
428                :   32位整数，文件头其余部分的字节长度，不包括其自身。前，它为零，并且第一个元组紧随其后。 将来对格式进行的更改可能会允许其他数据出现在文件头中。
429                    
430                    读取器应静默跳过任何不知道该怎么处理的文件头扩展数据。
431                    
432                    文件头扩展区被设想为包含一系列自识别块。 标志字段不是要告诉读取器扩展区中的内容。
433            
434            元组
435            :   每个元组都以元组中字段数的16位整数计数开头。然后，对于元组中的每个字段重复一次，存在一个32位长的字，后跟那么多字节的字段数据。
436                （长度字不包括自身，并且可以为零。） 在特殊情况下，-1表示NULL字段值。 在NULL情况下，没有值字节。
437                
438                字段之间没有对齐填充或任何其他额外数据。
439                
440                当前，二进制格式文件中的所有数据值都假定为二进制格式（格式代码1）。
441                可以预期，将来的扩展可能会添加一个文件头字段，以允许指定每列格式代码。
442                
443                如果文件中包含OID，则OID字段紧跟在字段计数字之后。 这是一个普通字段，只是它不包括在字段计数中。 特别是它有一个长度字，这将允许处理4字节和8字节的OID，而不会带来太多麻烦，并且如果确实需要的话，也可以将OID显示为null。
444            
445            文件尾
446            :   文件尾部由一个包含`-1`的16位整数字组成。这很容易与元组的字段计数字区分开。 如果字段计数字既不是`-1`也不是预期的列数，则读取器应报告错误。
447                
448                这提供了额外的检查，以防止以某种方式与数据不同步。
449
450
451
452
453## 示例
454
455使用竖线（|）作为字段定界符，将表复制到客户端：
456
457    ``` sql
458    COPY country TO STDOUT (DELIMITER '|');
459    ```
460    
461    将数据从文件复制到`country`表：
462    
463    ``` sql
464    COPY country FROM '/home/usr1/sql/country_data';
465    ```
466    
467    仅将名称以'A'开头的国家复制到文件中：
468    
469    ``` sql
470    COPY (SELECT * FROM country WHERE country_name LIKE 'A%') TO
471      '/home/usr1/sql/a_list_countries.copy';
472    ```
473    
474    使用单行错误隔离模式将数据从文件复制到`sales`表中并记录错误：
475    
476    ``` sql
477    COPY sales FROM '/home/usr1/sql/sales_data' LOG ERRORS
478       Executor REJECT LIMIT 10 ROWS;
479    ```
480    
481    若要复制Executor数据供以后使用，请使用`ON EXECUTOR`子句。 `COPY TO ON EXECUTOR`命令的使用形式如下：
482    
483    ``` sql
484    COPY table TO '<EXE_DATA_DIR>/scdumpname<EXEID>_suffix' ON EXECUTOR;
485    ```
486    
487    `<EXEID>`是必需的。 但是，您可以用绝对路径替换路径中的`<EXE_DATA_DIR>`字符串文字。
488    
489    将字符串文字`<EXE_DATA_DIR>`和`<EXEID>`传递给`COPY`时， 运行操作时`COPY`将填充适当的值。
490    
491    
492    例如，如果您的`mytable`包含以下Executor和mirror：
493    
494    ``` sql
495    contentid | dbid | file Executor location
496        0 | 1 | /home/usr1/data1/scsegdir0
497        0 | 3 | /home/usr1/data_mirror1/scsegdir0
498        1 | 4 | /home/usr1/data2/scsegdir1
499        1 | 2 | /home/usr1/data_mirror2/scsegdir1
500    ```
501    
502    运行命令：
503    
504    ``` sql
505    COPY mytable TO '<EXE_DATA_DIR>/scbackup<EXEID>.txt' ON EXECUTOR;
506    ```
507    
508    将会产生如下行：
509    
510    ``` sql
511    /home/usr1/data1/scsegdir0/scbackup0.txt
512    /home/usr1/data2/scsegdir1/scbackup1.txt
513    ```
514    
515    
516    第一列中的内容ID是插入文件路径中的标识符（例如，上面的`scsegdir0/scbackup0.txt`）。
517    文件是在Executor上而不是在coordinator上创建的，就像在标准`COPY`操作中那样。 使用`ON
518    Executor`复制时，不会为mirror创建任何数据文件。
519    
520    
521    如果指定了绝对路径，而不是`<EXE_DATA_DIR>`，例如在语句中
522    
523    ``` sql
524    COPY mytable TO '/tmp/scdir/scbackup_<EXEID>.txt' ON EXECUTOR;
525    ```
526    
527    
528    
529    文件将放置在每个Executor的`/tmp/scdir`中。 如果需要重新分发，`scfs`工具还可用于使用`ON
530    Executor`选项还原由`COPY TO`生成的数据文件。
531    
532    
533    注意: 可以使用诸如`scfs`之类的工具来还原数据。
534    备份/还原工具不适用于使用`COPY TO ON EXECUTOR`手动生成的文件。
535    
536    
537    
538    
539    本示例从`lineitem`表复制数据，并使用`PROGRAM`子句使用`cat`实用程序将数据添加到`/tmp/lineitem_program.csv`文件。
540    该文件放置在PalopgMPP数据库coordinator上。
541    
542    ``` sql
543    COPY LINEITEM TO PROGRAM 'cat > /tmp/lineitem.csv' CSV;
544    ```
545    
546    
547    
548    本示例使用`PROGRAM`和`ON EXECUTOR`子句将数据复制到Executor节点上的文件中。
549    在Executor节点上，`COPY`命令将`<EXEID>`替换为Executor content ID，以为Executor节点上的每个Executor实例创建一个文件。
550    
551    ``` sql
552    COPY LINEITEM TO PROGRAM 'cat > /tmp/lineitem_program<EXEID>.csv' ON EXECUTOR CSV;
553    ```
554    
555    
556    
557    本示例使用`PROGRAM`和`ON EXECUTOR`子句从Executor节点上的文件复制数据。
558    从文件复制数据时，`COPY`命令用Executor content ID替换`<EXEID>`。在Executor节点上，每个Executor实例必须有一个文件，其中文件名包含Executor节点上的Executor content ID。
559    
560    ``` sql
561    COPY LINEITEM_4 FROM PROGRAM 'cat /tmp/lineitem_program<EXEID>.csv' ON EXECUTOR CSV;
562    ```
563
564
565兼容性说明
566:   SQL标准中没有`COPY`语句。
567
568
569相关SQL命令
570:   `  CREATE EXTERNAL TABLE  `