gpload
按照一个YAML格式的控制文件的定义运行一个装载作业。
概要
gpload -f control_file [-l log_file] [-h hostname] [-p port]
[-U username] [-d database] [-W] [--gpfdist_timeout seconds]
[--no_auto_trans] [[-v | -V] [-q]] [-D]
gpload -?
gpload --version
先决条件
gpload
在其上被执行的客户端机器必须具有下列:
- Python 2.6.2或其后版本、
pygresql
(Python的PostgreSQL接口)以及pyyaml
。注意Python及所需的Python库被包括在Greenplum数据库服务器安装中,因此如果在gpload
运行的机器上安装有Greenplum数据库,用户就不需要单独的Python安装。 注意: Greenplum数据库Loaders for Windows supports only Python 2.5 (available from https://www.python.org). [gpfdist](gpfdist.html#topic1)
并行文件分发程序被安装并且处于$PATH
中。这个程序位于用户的Greenplum数据库服务器安装的$GPHOME/bin
中。- 往来Greenplum数据库阵列(Master和Segment)中所有主机的网络访问。
- 往来要被装载的数据所在的主机(ETL服务器)的网络访问。
描述
gpload
是一个数据装载工具,它扮演着Greenplum数据库外部表并行装载特性的接口的角色。通过一个用YAML格式化控制文件定义装载说明,gpload
调用Greenplum数据库的并行文件服务器([gpfdist](gpfdist.html)
)执行装载,基于源数据的定义创建一个外部表定义,并且指定INSERT
、UPDATE
或MERGE
操作把源数据装载到数据库中的目标表中。
在目标表上指定多个同时的装载操作时,操作包括在YAML控制文件(控制文件格式)的SQL
集合中指定的任何SQL命令会在单个事务中执行以防止不一致的数据。
选项
-f control_file
必需。包含装载说明详情的YAML文件。请见控制文件格式。 --gpfdist_timeout seconds
为gpfdist
并行文件分发程序发送响应设置超时时间。输入一个从0
到30
秒的值(输入“0
”会禁用超时)。注意在高流量网络上可能需要增加这个值。
-l log_file
指定在哪里写日志文件。默认是~/gpAdminLogs/gpload_YYYYMMDD
。有关日志文件的更多信息请见日志文件格式。
--no_auto_trans
如果用户在目标表上执行单个装载操作,可指定--no_auto_trans
禁用把装载操作作为单个事务处理的特性。
默认情况下,在一个目标表上执行多个同时的操作时,gpload
把每个装载操作处理为单个事务以防止不一致的数据。
-q (无屏幕输出)
运行在静默模式中。命令输出不会被显示在屏幕上,但仍将被写入到日志文件。
-D (调试模式)
检查错误情况,但是不执行装载。
-v (详细模式)
在装载步骤被执行时,显示它们的详细输出。
-V (非常详细模式)
显示非常详细的输出。
-? (显示帮助)
显示帮助,然后退出。
--version
显示这个工具的版本,然后退出。
连接选项
-d database
要装载到的数据库。如果没有指定,则从装载控制文件、环境变量$PGDATABASE
读取或者默认为当前系统用户名。
-h hostname
指定Greenplum的Master数据库服务器在其上运行的机器的主机名。如果没有指定,会从装载控制文件、环境变量$PGHOST
读取或者默认为localhost
。
-p port
指定Greenplum的Master数据库服务器在其上监听连接的TCP端口。如果没有指定,会从装载控制文件、环境变量$PGPORT
读取或者默认为5432。
-U username
要用其进行连接的数据库角色名。如果没有指定,会从装载控制文件、环境变量$PGUSER
读取或者默认为当前系统用户名。
-W (强制口令提示)
强制口令提示。如果没有指定,会从环境变量$PGPASSWORD
、 $PGPASSFILE
指定的口令文件或~/.pgpass
中的口令文件中读取口令。如果这些都没有设置,即使没有提供-W
,gpload
也将提示要求一个口令。
控制文件格式
gpload
控制文件使用YAML 1.1文档格式,然后为定义Greenplum数据库装载操作的多个步骤实现了其自身的模式。该控制文件必须是一个有效的YAML文档。
gpload
程序按顺序处理控制文件文档并且使用缩进(空格)来判断文档层次以及小节之间的关系。空格的使用是有意义的。不能把空格简单地用于格式化目的,并且完全不能使用制表符。
一个装载控制文件的基础结构是:
---
[VERSION](#topic1__cfversion): 1.0.0.1
[DATABASE](#topic1__cfdatabase): db_name
[USER](#topic1__cfuser): db_username
[HOST](#topic1__cfhost): master_hostname
[PORT](#topic1__cfport): master_port
[GPLOAD](#topic1__cfgpload):
[INPUT](#topic1__cfinput):
- [SOURCE](#topic1__cfsource):
[LOCAL_HOSTNAME](#topic1__cfsourcelocalname):
- hostname_or_ip
[PORT](#topic1__cfsourceport): http_port
| [PORT_RANGE](#topic1__cfversion): [start_port_range, end_port_range]
[FILE](#topic1__cfsourcefile):
- /path/to/input_file
[SSL](#topic1__cfsourcessl): true | false
[CERTIFICATES_PATH](#topic1__cfsourcecertificatespath): /path/to/certificates
- [FULLY_QUALIFIED_DOMAIN_NAME](#topic1__fqdn): true | false
- [COLUMNS](#topic1__cfcolumns):
- field_name: data_type
- [TRANSFORM](#topic1__cftransform): 'transformation'
- [TRANSFORM_CONFIG](#topic1__cftransformconfig): 'configuration-file-path'
- [MAX_LINE_LENGTH](#topic1__cfmaxlinelength): integer
- [FORMAT](#topic1__cfformat): text | csv
- [DELIMITER](#topic1__cfdelimiter): 'delimiter_character'
- [ESCAPE](#topic1__cfescape): 'escape_character' | 'OFF'
- [NULL_AS](#topic1__cfnullas): 'null_string'
- [FORCE_NOT_NULL](#topic1__cfforcenotnull): true | false
- [QUOTE](#topic1__cfquote): 'csv_quote_character'
- [HEADER](#topic1__cfheader): true | false
- [ENCODING](#topic1__cfencoding): database_encoding
- [ERROR_LIMIT](#topic1__cferrorlimit): integer
- [LOG_ERRORS](#topic1__cferrorlog): true | false
[EXTERNAL](#topic1__cfexternal):
- [SCHEMA](#topic1__cfschema): schema | '%'
[OUTPUT](#topic1__cfoutput):
- [TABLE](#topic1__cftable): schema.table_name
- [MODE](#topic1__cfmode): insert | update | merge
- [MATCH_COLUMNS](#topic1__cfmatchcolumns):
- target_column_name
- [UPDATE_COLUMNS](#topic1__cfupdatecolumns):
- target_column_name
- [UPDATE_CONDITION](#topic1__cfupdatecondition): 'boolean_condition'
- [MAPPING](#topic1__cfmapping):
target_column_name: source_column_name | 'expression'
[PRELOAD](#topic1__cfpreload):
- [TRUNCATE](#topic1__cftruncate): true | false
- [REUSE_TABLES](#topic1__cfreusetables): true | false
[SQL](#topic1__cfsql):
- [BEFORE](#topic1__cfbefore): "sql_command"
- [AFTER](#topic1__cfafter): "sql_command"
VERSION
可选。gpload
控制文件模式的版本。当前版本是1.0.0.1。
DATABASE
可选。指定Greenplum数据库系统要连接到哪个数据库。如果没有指定则默认为$PGDATABASE
。如果$PGDATABASE
也没有设置,则默认为当前系统用户名。用户还可以在命令行上用-d
选项指定数据库。
USER
可选。指定用于连接的数据库角色。如果没有指定,默认为当前用户或者$PGUSER
(如果设置)。用户还可以在命令行上用-U
选项指定数据库角色。
如果运行gpload
的用户不是Greenplum数据库的超级用户,那么必须为该用户授予适当的权力。更多信息请见Greenplum数据库参考指南。
HOST
可选。指定Greenplum数据库的Master主机名。如果没有指定,默认为localhost或者$PGHOST
(如果设置)。用户还可以在命令行上用-h
选项指定Master主机名。
PORT
可选。指定Greenplum数据库的Master端口。如果没有指定,默认为5432或者$PGPORT
(如果设置)。用户还可以在命令行上用-p
选项指定Master端口。
GPLOAD
必需。开始装载说明小节。GPLOAD
说明必须定义有一个INPUT
小节和一个OUTPUT
小节。
INPUT
必需。定义要装载的输入数据的位置和格式。gpload
将在当前主机上启动[gpfdist](gpfdist.html#topic1)
文件分布程序的一个或者更多实例并且在Greenplum数据库中创建指向源数据的外部表定义。注意在其上运行gpload
的主机必须对所有的Greenplum数据库主机(Master和Segment)通过网络可访问。
SOURCE
必需。INPUT
说明的SOURCE
块定义源文件的位置。一个INPUT
小节可以定义多个SOURCE
块。每个定义的SOURCE
块对应于将在本地机器上启动的一个[gpfdist](gpfdist.html#topic1)
文件分布程序的实例。每个定义的SOURCE
块必须有一个FILE
说明。更多关于使用gpfdist
并行文件服务器和单个以及多个gpfdist
实例的信息,请见Greenplum数据库管理员指南中的“装载和卸载数据”。
LOCAL_HOSTNAME
可选。指定gpload
运行其上的本地机器的主机名或者IP地址。如果这个机器被配置有多个网络接口卡(NIC),用户可以指定每块NIC的主机名或者IP,以便允许网络流量同时使用所有的NIC。默认是仅使用本地机器的主要主机名或者IP。
PORT
可选。指定[gpfdist](gpfdist.html#topic1)
文件分布程序应该使用的特定端口号。用户还可以提供一个PORT_RANGE
来从指定的范围中选择可用的端口。如果PORT
和PORT_RANGE
同时被定义,那么PORT
优先。如果PORT
和PORT_RANGE
都没有定义,默认为在8000和9000之间选择一个可用端口。如果在LOCAL_HOSTNAME
中声明多个主机名,这个端口号被用于所有主机。如果用户想要使用所有的NIC装载一个给定目录位置的同一个文件或者文件集合,这种配置就是用户想要的。
PORT_RANGE
可选。可被用来代替PORT
提供一个端口号范围,gpload
可以从其中为这个[gpfdist](gpfdist.html#topic1)
文件分布程序实例选择一个可用的端口。
FILE
必需。指定本地文件系统上的一个文件位置、命名管道或者目录位置,其中包含要被装载的数据。用户可以声明多于一个文件,只要所有指定文件中数据的格式相同。如果这些文件被使用gzip
或者bzip2
(有.gz
或者.bz2
文件扩展名)压缩,这些文件将被自动解压缩(在用户路径中有gunzip
或者bunzip2
)。
在指定要装载哪些源文件时,用户可以使用通配符(*
)或其他C风格的模式匹配来指示多个文件。被指定的文件假定在相对于gpload
被执行的当前目录的位置(或者用户可以声明绝对路径)。
SSL
可选。指定SSL加密的使用。如果SSL
被设置为true,gpload
用--ssl
启动 gpfdist
服务器并且使用gpfdists://
协议。
CERTIFICATES_PATH
当SSL为true
时必需;当SSL为false
或者没有指定时不能指定这个参数。CERTIFICATES_PATH
中指定的位置必须包含下列文件:* 服务器证书文件server.crt
- 服务器私钥文件
server.key
- 可信证书机构
root.crt
根目录(/
)不能被指定为CERTIFICATES_PATH
。
FULLY_QUALIFIED_DOMAIN_NAME
可选。指定gpload
是否把主机名解析成完全限定的域名(FQDN)或者本地主机名。如果值被设置为true
,名称会被解析到FQDN。如果该值被设置为false
,则解析到本地主机名。默认是false
。在某些情况下可能要求一个完全限定的域名。例如,如果Greenplum数据库系统在与ETL应用不同的域且该域能够被gpload
。
COLUMNS
可选。以field_name:data_type
这样的格式指定源数据文件的模式。源文件中的DELIMITER
字符是分隔两个数据值域(列)的东西。一行由一个换行字符(0x0a
决定)。如果输入COLUMNS
没有指定,则使用输出TABLE
的模式,意味着源数据必须与目标表具有相同的列序、列数以及数据格式。
默认的source-to-target映射基于这一节定义的列名与目标TABLE
中列名之间的匹配。默认映射可以使用MAPPING
小节覆盖。
TRANSFORM
可选。指定传递给gpload
的输入转换的名字。有关XML转换的信息,请见Greenplum数据库管理员指南中的“装载和卸载数据”。
TRANSFORM_CONFIG
当Required when TRANSFORM
被指定时,这个元素是必需的。指定在上面TRANSFORM
参数中指定的转换的配置文件位置。
MAX_LINE_LENGTH
可选。一个整数,指定传递给gpload
的XML转换数据中一行的最大长度。
FORMAT
可选。指定源数据文件的格式:纯文本(TEXT
)格式,逗号分隔值(CSV
)格式。如果没有指定,这个默认为TEXT
。更多有关源数据格式的信息,请见Greenplum数据库管理员指南中的“装载和卸载数据”。
DELIMITER
可选。指定在每行数据内分隔列的单个ASCII字符。在TEXT模式中默认是一个制表符,在CSV模式中默认是一个逗号。用户还可以指定一个非可打印ASCII字符或者非可打印Unicode字符,例如:"\x1B"
或者 "\u001B"
。对于非可打印字符也支持转义字符串语法E'character-code'
。ASCII或Unicode字符必须被封闭在单引号中。例如:E'\x1B'
或者E'\u001B'
。
ESCAPE
指定用于C转义序列(例如\n
、\t
、\100
等等)以及转义可能被当作行列定界符的数据字符的单个字符。确保选择一个在实际列数据中任何地方都没有使用的转义字符。文本格式文件的默认转义字符是一个\(反斜线),csv格式文件的默认转义字符是一个"
(双引号)。不过可以指定另一个字符来表示转义。还可以在文本格式文件中通过指定'OFF'
值作为转义值来禁用转义。这对于其中嵌有很多不准备作为转义字符的反斜线的文本格式的Web日志数据非常有用。
NULL_AS
可选。指定表示空值的字符串。TEXT
模式中默认是\N
(反斜线-N),CSV
模式中默认是没有引用的空的值。即便在TEXT
模式中,对于想要把空值与空字符串区分开来的情况,用户也可以使用空字符串。任何匹配这个字符串的源数据项将被认为是一个空值。
FORCE_NOT_NULL
可选。在CSV模式中,处理每个被指定的列,仿佛它被引用并且因此不是一个NULL值。对于CSV模式中的默认空值字符串(两个定界符之间什么都没有),这导致缺失的值被计算为长度为零的字符串。
QUOTE
当FORMAT
是CSV
时,这个元素是必需的。为CSV
模式指定引用字符。默认是双引号("
)。
HEADER
可选。指定数据文件中的第一行是一个头部行(包含列名)并且不应被包括在要被装载的数据中。如果使用多个数据源文件,所有的文件必须有一个头部行。默认是假定输入文件没有头部行。
ENCODING
可选。源数据的字符集编码。可指定一个字符串常量(例如'SQL_ASCII'
)、一个整数编码编号,或者指定'DEFAULT'
以使用默认客户端编码。如果没有指定,默认的客户端编码会被使用。有关支持的字符集的信息,请见Greenplum数据库参考指南。
ERROR_LIMIT
可选。为这个装载操作启用单行错误隔离模式。当被启用时,在输入被处理期间只要没有达到错误限制计数,任何Greenplum数据库Segment会抛弃有格式错误的输入行。如果错误限制没有达到,所有好的行将会被装载并且任何错误行都将被抛弃或者被捕捉在错误日志信息中。默认是在遇到第一个错误时中止装载操作。注意单行错误隔离只适用于有格式错误的数据行,例如有额外或者缺失的属性、有错误数据类型的属性或者有无效的客户端编码序列。如果遇到约束错误(例如主键约束)仍将导致装载操作中止。有关处理装载错误的信息,请见Greenplum数据库管理员指南中的“装载和卸载数据”。
LOG_ERRORS
当ERROR_LIMIT
被声明时,这个元素是可选的。值可以是true
或者false
。默认值是false
。如果值是true
,当运行在单行错误隔离模式中时,格式错误的行会被内部记录下来。用户可以用Greenplum数据库的内建SQL函数gp_read_error_log('table_name')
检查格式错误。如果在装载数据时检测到格式错误,gpload
会用包含错误信息的表的名字生成一个警告消息,看起来类似于这个消息。
timestamp|WARN|1 bad row, please use GPDB built-in function gp_read_error_log('table-name')
to access the detailed error row
如果LOG_ERRORS: true
被指定,必须指定REUSE_TABLES: true
以便在Greenplum数据库的错误日志中保留格式错误。如果没有指定REUSE_TABLES: true
,错误信息会在gpload
操作后被删除。只有关于格式错误的总结信息会被返回。用户可以用Greenplum数据库的函数gp_truncate_error_log()
从错误日志中删除格式错误。
更多有关处理装载错误的信息,请见Greenplum数据库管理员指南中的“装载和卸载数据”。有关gp_read_error_log()
函数的信息,请见Greenplum数据库参考指南中的CREATE EXTERNAL TABLE
命令。
EXTERNAL
可选。定义gpload
创建的外部表数据库对象所属的方案。
默认是使用Greenplum数据库的search_path
。
SCHEMA
当EXTERNAL
被声明时,这个元素是必需的。外部表所在的方案的名称。如果该方案不存在,会返回一个错误。
如果%
(百分号字符)被指定,会使用OUTPUT
小节中TABLE
指定的表名的方案。如果这个表名没有指定一个方案,则会使用默认方案。
OUTPUT
必需。定义要被装载到数据库中的目标表和最终数据列值。
TABLE
必需。要装载到其中的目标表名。
MODE
可选。如果没有指定,则默认为INSERT
。有三种可用的装载模式:
INSERT - 使用下列方法装载数据到目标表中:
INSERT INTO target_table SELECT * FROM input_data;
UPDATE - 更新目标表中MATCH_COLUMNS
属性值等于输入数据并且UPDATE_CONDITION
为true(可选条件)的行的UPDATE_COLUMNS
。
MERGE - 插入新行并且更新FOOBAR
属性值等于相应输入数据而且MATCH_COLUMNS
为true(可选条件)的已有行的UPDATE_COLUMNS
。当源数据中的MATCH_COLUMNS
值在目标表数据中没有相应值时会被标识成新行。在那种情况下,源文件中的整个行会被插入,而不仅仅是MATCH
和UPDATE
列。如果有多个相等的新MATCH_COLUMNS
值,只有其中一个新行将被插入。使用UPDATE_CONDITION
可过滤掉要抛弃的行。
MATCH_COLUMNS
如果MODE
为UPDATE
或者MERGE
,则这个元素是必需的。指定被用作更新的连接条件的列。对于要在目标表中更新的行,指定目标列中的属性值必须等于相应的源数据列值。
UPDATE_COLUMNS
如果MODE
为UPDATE
或者MERGE
,则这个元素是必需的。指定对符合MATCH_COLUMNS
条件和可选UPDATE_CONDITION
的行要更新的列。
UPDATE_CONDITION
可选。指定目标表中要被更新的行(在MERGE
情况下是要被插入的行)必须满足的一个布尔条件(类似于在WHERE
子句中声明的那样)。
MAPPING
可选。如果指定一个映射,它会覆盖默认的source-to-target列映射。默认的source-to-target映射基于源COLUMNS
小节定义的列名与目标TABLE
中列名之间的匹配。映射可以被指定为:
target_column_name:
source_column_name
或者
target_column_name:
'expression'
其中expression是在查询的SELECT
列表中指定的任意表达式,例如常量值、列引用、操作符调用、函数调用等等。
PRELOAD
可选。指定在装载操作之前运行的操作。目前唯一的预装载操作是TRUNCATE
。
TRUNCATE
可选。如果设置为true,gpload
将在装载目标表之前移除其中所有的行。
REUSE_TABLES
可选。如果设置为true,gpload
将不会删除它创建的外部表对象和阶段性对象。这些对象将被重用于未来使用同一装载说明的装载操作。这会提高小型装载的性能(正在进行的到同一目标表的小型装载)。
如果LOG_ERRORS: true
被指定,REUSE_TABLES: true
必须被指定以保留Greenplum数据库错误日志中的格式错误。如果REUSE_TABLES: true
没有被指定,格式错误信息会在gpload
操作之后被删除。
SQL
可选。定义在装载操作之前或者之后要运行的SQL命令。用户可以指定多个BEFORE
或者AFTER
命令。按照想要的执行顺序列出命令。
BEFORE
可选。在装载操作开始之前要运行的一个SQL命令。将命令封闭在引号中。
AFTER
可选。在装载操作完成之后要运行的一个SQL命令。将命令封闭在引号中。
日志文件格式
gpload
输出的日志文件具有下面的格式:
timestamp|level|message
其中timestamp的形式是: YYYY-MM-DD HH:MM:SS
,level是DEBUG
、LOG
、INFO
、ERROR
中间的一个,而message是普通文本消息。
日志文件中可能让人感兴趣的一些INFO
消息是(其中#对应于实际的秒数、数据的单位或者失败的行):
INFO|running time: #.## seconds
INFO|transferred #.# kB of #.# kB.
INFO|gpload succeeded
INFO|gpload succeeded with warnings
INFO|gpload failed
INFO|1 bad row
INFO|# bad rows
注解
如果用户的数据库对象名使用双引号标识符(定界的标识符)创建,用户必须在gpload
控制文件中用单引号指定定界的名称。例如,如果用户这样创建一个表:
CREATE TABLE "MyTable" ("MyColumn" text);
用户的YAML格式的gpload
控制文件应该按如下方式引用上述表和列名:
- COLUMNS:
- '"MyColumn"': text
OUTPUT:
- TABLE: public.'"MyTable"'
示例
按my_load.yml
中的定义运行一个装载作业:
gpload -f my_load.yml
装载控制文件的例子:
---
VERSION: 1.0.0.1
DATABASE: ops
USER: gpadmin
HOST: mdw-1
PORT: 5432
GPLOAD:
INPUT:
- SOURCE:
LOCAL_HOSTNAME:
- etl1-1
- etl1-2
- etl1-3
- etl1-4
PORT: 8081
FILE:
- /var/load/data/*
- COLUMNS:
- name: text
- amount: float4
- category: text
- desc: text
- date: date
- FORMAT: text
- DELIMITER: '|'
- ERROR_LIMIT: 25
- LOG_ERRORS: true
OUTPUT:
- TABLE: payables.expenses
- MODE: INSERT
PRELOAD:
- REUSE_TABLES: true
SQL:
- BEFORE: "INSERT INTO audit VALUES('start', current_timestamp)"
- AFTER: "INSERT INTO audit VALUES('end', current_timestamp)"
另见
[gpfdist](gpfdist.html#topic1)
、Greenplum数据库参考指南中的CREATE EXTERNAL TABLE