GBase 8a MPP Cluster 远程导出功能使用说明

1. 概述

  GBase 8a MPP（下文简称“8a集群”）支持多种数据导出方式，根据导出文件位置的不同，8a集群的数据导出功能可分为：远程导出、本地导出、HDFS导出、FTP/SFTP导出。远程导出功能支持将数据从集群服务器导出到集群客户端所在的机器，导出后的数据为文本文件。下文将会介绍远程导出的语法和参数，同时列举出一些参数在使用时需要注意的事项。

2. 功能说明

2.1 SQL 语法

rmt:<select_syntax> INTO OUTFILE '<file_path>' [OUTFILE_OPTIONS];

• 参数说明

  字段名称	含义说明
  select_syntax	SELECT语法
  file_path	保存导出数据的路径及文件名
  OUTFILE_OPTIONS	数据导出的规则

• OUTFILE_OPTIONS 参数说明

  字段名称	含义说明
  FIELDS/COLUMNS TERMINATED BY	字段分隔符，支持多个字符。 默认值为 \t，即 TAB 键
  FIELDS/COLUMNS [OPTIONALLY] ENCLOSED BY	字段包围符，可以自行指定单个字符为字段包围符，指定多个字符时报错。 支持 OPTIONALLY 选项，该选项表示字段包围符仅对字符串类型字段生效。 默认无包围符。
  FIELDS/COLUMNS [OPTIONALLY] DOUBLE_ENCLOSED BY	字段包围符自转义，该参数包含上面参数（字段包围符）的所有功能，但额外的作用是，当转义符设置为空时，若果某字段满足使用字段包围符的条件，且该字段中还有与字段包围符相同的字符，则将该字符通过双写的方式自转义。
  FIELDS/COLUMNS ESCAPED BY	转义标识符，可以自行指定单个字符为转义标识符，指定多个字符时报错。 默认值为 \，默认值在语句中写为 FIELDS ESCAPED BY '\\'。
  LINES STARTING BY	行起始符，支持多个字符。默认值为空。
  LINES TERMINATED BY	行分隔符，支持多个字符。默认值为 \n。
  NULL_VALUE	空值标识符，支持多个字符。默认值为 \N。
  WRITEMODE BY	*V95版本新增参数 写入方式，可选值为：NORMAL 或 OVERWRITES。 NORMAL：（默认值）如果文件已存在则报错。 OVERWRITES：覆盖已存在文件。
  FILESIZE	*V95版本新增参数 导出文件的最大大小，取值范围 [0 , 264-1]。 如果导出文件大小大于此参数值，则分裂产生新文件。 默认值为0，表示不限制导出文件的大小。 FILESIZE 值支持 k/K/m/M/g/G 后缀表示方法。
  CHARACTER SET	指定导出文件的字符集，支持 GBK 和 UTF8 编码。 如果不指定，则默认导出和源表字符集保持一致。
  FIELDS/COLUMNS LENGTH	在使用定长模式导出时，用于设定字段长度的参数。定长格式数据导出时，设置每个字段的长度，多个字段之间用逗号分隔，该参数不能和列分隔符以及包围符混用。
  WITH HEAD	[ 可选参数 ] 指定导出数据文件中带有表头信息。不指定该参数时导出数据文件中不带有表头信息。 WITH HEAD 语法约束：   1. 对于表头导出功能，当用户指定转义字符时，表头信息不作转义处理。   2. 表头的导出仅支持 express 引擎表，其他类型不作保证。

• 注意事项

  • rmt: 与 select_syntax 之间不能有空格。
  • file_path，以及 FIELD_OPTION 中的字段分隔符、字段包围符、转义标识符等均必须使用单引号 ' 包围，否则无法正常导出数据。
  • 远程导出不支持顶层查询是 UNION 类查询。
  • 远程导出的目标文件如果已经在本地存在，则不能通过 SELECT @@error_count 来获取错误数，原因是文件是否存在由客户端判断，而 @@error_count 是服务端变量。
    
    

2.2 导出路径

  根据导出语法规定，远程导出路径需在 SQL 语句中指定，否则报错。根据指定的导出路径的形式，文件的创建分为以下两种情况：

  1. 指定为绝对路径：
    文件保存在指定的导出路径中。

  2. 指定为相对路径：
    导出文件的路径为用户登录客户端时所在目录 + SQL 语句中指定的相对路径。
    例如：用户登录客户端时所在的目录为 /opt，再使用 rmt:SELECT * FROM t INTO OUTFILE 'test/rmtexp.tbl' 进行远程导出操作，则最终导出文件的完整路径为 /opt/test/rmtexp.tbl。

2.3 导出端口

  8a集群的远程导出功能的实现方式为：数据节点根据管理节点下发的 SQL 中的 IP 和端口号与客户端建立连接，将结果集发送给客户端后，客户端将数据导出为文件。

  远程导出功能默认使用导出客户端所在机器的 16066 - 16165 端口范围作为导出服务的临时端口。其端口范围可通过修改配置文件参数进行配置，参数如下表所示。

• 导出端口参数

  名称	最小值	最大值	默认值
  remote_export_min_port	1025	65535	16066
  remote_export_max_port	1025	65535	16166

• 注意：
    使用远程导出功能前请先确认该端口范围正常开放，且未被占用，否则可能导致远程导出失败。
  
  

3. 其他说明

3.1 FILESIZE 功能说明

❗️ 重要提示：远程导出功能需要客户端启动两个线程分别用于数据接收和文件写入，在集群数据生产速度稳定的前提下，如果总导出速度取决于客户端的文件写入速度，那么文件自动分裂，即 FILESIZE 功能对导出性能可能会产生负面影响。FILESIZE 值越小（非0），越需要频繁对接收的数据做拆行处理，更多的拆行处理将会占用更多的时间，也降低了单次写入磁盘的数据量，最终将导致导出性能下降。故建议在使用文件自动分裂功能时，尽可能使用较大的 FILESIZE 值。

3.1.1 分裂文件的命名规则

  远程导出文件自动分裂的命名规则为：file_title + suffix + file_ext。其中：
  file_title 是 OUTFILE 参数指定的 file_name 中最前面的 ‘.’ 之前的部分（不含 ‘.’）；
  suffix 是自动追加的文件名后缀，第一个文件名后缀是 ‘_p1’，以后每个文件名后缀依次是 ‘_p2’、’_p3’……。FILESIZE 为 0 时文件不分裂，生成文件名与 file_name 相同，不追加 ‘_pN’ 后缀；
  file_ext 是 OUTFILE 参数指定的 file_name 中最前面的 ‘.’ 之后的部分（包含 ‘.’）。
  例如：执行 rmt:SELECT * FROM t INTO OUTFILE '/tmp/t.tbl' FILESIZE 10m;，此时导出文件名为 t_p1.tbl、t_p2.tbl …… t_pN.tbl。

3.1.2 文件分裂的存储控制

  远程导出使用文件自动分裂功能后，一次导出可能会生成多个文件。当使用相同文件名进行多次导出时，每次生成的文件数可能不同。当某次导出任务比之前的导出任务生成的文件数少时，导出后可能有相似后缀 _pN 的脏文件遗留。这会导致其他的导入程序无法准确识别某次导出任务的文件。

  为解决以上问题，可在客户端配置文件中增加 remote_export_create_directory 参数，控制是否自动创建与导出文件同名的目录。

  在 remote_export_create_directory=1 的情况下，自动创建与导出文件同名的目录，并在该目录下生成导出文件。如果导出前该目录已存在，当指定 WRITEMODE BY NORMAL （或者不指定 WRITEMODE BY）时，该目录不为空则报错；当指定 WRITEMODE BY OVERWRITES 时，该目录不为空则自动清空目录。