search-icon search-icon

#yasldr使用指导

# 查看帮助

使用yasldr -H命令可查看帮助信息。

$ yasldr -H

# 查看版本

使用yasldr -V命令可查看版本信息。

$ yasldr -V

# 命令格式

$ YASLDR USERNAME/PASSWORD@IP:PORT {LOAD Options} {LOAD Statement}

USERNAME/PASSWORD@IP:PORT

执行导入命令的数据库用户名、密码、地址，地址默认值为127.0.0.1:1688。

对该用户的权限要求为：

1.对要导入的表应该拥有写权限和查询权限。

2.执行分布式数据库导入时，用户还需要如下系统表权限：

ROUTE$，NODE_INFO$，DIST$，OBJ$，DISTCOL$，TAB$，USER$

GRANT SELECT ON sys.route$ TO USER;
GRANT SELECT ON sys.node_info$ TO USER;
GRANT SELECT ON sys.dist$ TO USER;
GRANT SELECT ON sys.obj$ TO USER;
GRANT SELECT ON sys.distcol$ TO USER;
GRANT SELECT ON sys.tab$ TO USER;
GRANT SELECT ON sys.USER$ TO USER;

3.分布式数据库导入支持连接CN主节点地址和DN主节点地址，若连接备节点则会返回错误。

#以DN备节点地址127.0.0.1:1701为例
$ yasldr sales/sales@127.0.0.1:1701 batch_size=4032 control_text="'LOAD DATA INFILE '/home/yasdb/area.csv' FIELDS TERMINATED BY '|' optionally enclosed by '\"' INTO TABLE area (area_no,area_name,dhq) '"

YashanDB Loader Release 22.2.0.9 x86_64 bbd4bd4
YAS-04880 invalid node type
[YASLDR] execute failed

4.分布式数据库导入数据至复制表仅能通过直连DN主节点的方式进行导入，否则返回错误。

# LOAD Options

导入命令选项，可同时指定多个。

  • BATCH_SIZE：每批次的CSV数据行数，默认4032，范围[1,65535]。
  • MODE：导入方式，包括BASIC方式和BATCH方式，默认BATCH方式。
  • PACKET_SIZE*：协议包大小，单位为字节，仅语法兼容。默认131072，范围[65536，524288]。
  • CONN_POOL_SIZE：连接池的大小，默认5，范围[1,32]。

BATCH导入方式不支持interval分区，如需导入具有interval分区的表请在单机部署下选择BASIC方式导入。

BASIC导入方式不支持容错处理，在遇到错误数据或数据违反约束时yasldr会报错退出。

SPLIT模式下仅做文件拆分，不会进行数据导入，因此不会创建连接池。

# LOAD Statement

# 指定方式

指定LOAD语句，可以为如下方式：

  • CONTROL_FILE：含有单条LOAD语句的控制文件。

    示例

    #准备本地CSV文件（以/home/yasdb/area.csv为例）
$ vi /home/yasdb/area.csv
12|load|1201|loadbranch|12
13|load|1301|loadbranch|13

$ vi /home/yasdb/load.ctl
LOAD DATA INFILE '/home/yasdb/area.csv' FIELDS TERMINATED BY '|' optionally enclosed by '"' INTO TABLE branches (branch_no,branch_name,area_no)

$ yasldr sales/sales@127.0.0.1:1688 batch_size=4032 mode=batch packet_size=131072 control_file=/home/yasdb/load.ctl
YashanDB LOADER VERSION: RELEASE 1.0.0.0
[YASLDR] import succeeded

  • CONTROL_TEXT：以双引号+单引号包围的单条LOAD语句，只有不指定CONTROL_FILE且指定CONTROL_TEXT时才被选用。

    示例

    #准备本地CSV文件（以/home/yasdb/area.csv为例）
$ vi /home/yasdb/area.csv
12|load|1201|loadbranch|12
13|load|1301|loadbranch|13

$ yasldr sales/sales@127.0.0.1:1688 batch_size=4032 control_text="'LOAD DATA INFILE '/home/yasdb/area.csv' FIELDS TERMINATED BY '|' optionally enclosed by '\"' INTO TABLE area (area_no,area_name,dhq) '"
YashanDB LOADER VERSION: RELEASE 1.0.0.0
[YASLDR] import succeeded

Note：

使用CONTROL_TEXT指定时，需同时满足操作系统对特殊字符的转义要求，例如在Linux下对双引号需使用\转义。

# 语句内容

yasldr工具中执行的LOAD语句与LOAD DATA具有相同的语法格式，部分约束不同，相同部分可参考LOAD DATA章节描述。

syntax
LOAD DATA option_clause input_file_clause bad_file_clause discard_file_clause table_clause
# option_clause
syntax
OPTIONS ( PARAMETER_NAME = PARAMETER_VALUE )

该语句用于指定加载操作的相关选项。

# ENABLE_BULK

当其值为TRUE时，yasldr工具使用bulkload模式导入LSC表，不支持导入TAC和HEAP表。

parameter_value须为TRUE或FALSE，默认值为FALSE。

# ERRORS

指定数据导入的容错数据条数上限，当数据错误条数达到上限时，终止数据导入。由于数据库服务端不感知该参数，在完成数据导入后数据库客户端会校验该参数，此时若服务端的容错数量超过指定的errors参数，可能会导致实际打印的error数据大于该值。

parameter_value须为一个范围在[0,4294967295]之间的整数，默认值是50。

# RUN_LEVEL

该选项用于指定程序执行的任务类型。

SPLIT模式

执行csv文件拆分的任务，但不执行数据导入。

大数据量情况下（超过500G），建议先执行此命令将csv文件进行拆分后再导入。

为方便用户使用，YashanDB提供一键拆分csv文件和导入csv文件的功能，见工具手册数据导入命令中描述。

需注意的是，yasboot要求执行导入的数据库实例已纳入OM管理，否则需先进行托管。

SPLIT模式仅在使用yasldr工具进行数据导入时实现，无法直接通过LOAD DATA语句使用该模式。

默认不进行文件拆分操作，指定该选项后才进行文件拆分操作。

示例

#area.csv文件内容为:
6|load|601|loadbranch|6
7|load|701|loadbranch|7

$ yasldr sales/sales@127.0.0.1:1688 batch_size=4032 control_text="'LOAD DATA OPTIONS(RUN_LEVEL=SPLIT,DEGREE_OF_PARALLELISM=2) INFILE '/home/yasdb/area.csv' FIELDS TERMINATED BY '|' OPTIONALLY ENCLOSED BY '\"' APPEND INTO TABLE area(area_no,area_name,dhq) directory '/home/yasdb/file''"
# LOG

指定生成日志文件，记录执行数据加载任务的过程中过程信息，包括数据导入失败原因，导入成功条数等信息，与input_file_clause语句指定的导入文件相关。无论是否指定本参数，均会生成日志文件，省略则默认在首个导入文件目录下生成与该文件同名，后缀为log的日志文件。

parameter_value支持相对路径及绝对路径，仅支持指定到文件名。

Note:

YashanDB数据导入生成日志文件的相关参数有SILENT、STATS和LOG，三种参数的关系如下：

  • SILENT为TRUE时，STATS和LOG参数失效，此时不会生成导入日志、错误数据文件和过滤数据文件。
  • SILENT为FALSE时：
    • STATS为TRUE，日志文件内包含统计信息。
    • STATS为FALSE，日志文件内不包含统计信息，仅包含过程信息。

示例

#自行创建area_log.csv文件，文件内容为:
1|load|101|loadbranch|1|2
2|load|201|loadbranch|2|2

$ yasldr sales/sales@127.0.0.1:1688 batch_size=4032 control_text="'LOAD DATA OPTIONS(DEGREE_OF_PARALLELISM=2,LOG='/home/yasdb/area_log.log') INFILE '/home/yasdb/area_log.csv' fields terminated by '|' INTO TABLE area(area_no,area_name,dhq)'"

--日志文件内容
YashanDB Loader Release 22.2.7.200 x86_64 c877471
Production on 2023-09-15 02:48:27.353

Table AREA:
column_name                                                        infile_column
AREA_NO                                                            1
AREA_NAME                                                          2
DHQ                                                                3


Table AREA:
  2 logical rows read.
  2 rows successfully loaded.
  0 rows not loaded due to data errors.
  0 rows not loaded because all fields were null.

Elapsed time was: 00:00:00.05
# SILENT

指定导入过程中是否生成记录文件，包括日志文件、错误数据文件及过滤数据文件。当其值为TRUE，表示不生成记录文件；值为FALSE，表示生成记录文件。

parameter_value须为TRUE或FALSE，默认值为FALSE。

# STATS

指定是否打印导入过程中的统计信息。值为TRUE时，会将导入过程中的统计信息打印输出到日志中；值为FALSE时，不会打印统计信息。打印输出信息的日志会保存至导入数据文件所在的路径中，且与该数据文件同名，文件格式为log格式。

parameter_value须为TRUE或FALSE，默认值为FALSE。

具体打印的统计信息如下：

  • 导入对象
  • READER、BINDER线程的数量、时间和内存
  • 收发数据所需时间及内存
  • 总时间及内存

示例

#自行创建area_stats.csv文件，文件内容为:
1|load|101|loadbranch|1
2|load|201|loadbranch|2

    
$ yasldr sales/sales@127.0.0.1:1688 batch_size=4032 control_text="'LOAD DATA OPTIONS(DEGREE_OF_PARALLELISM=2,STATS=TRUE) INFILE '/home/yasdb/area_stats.csv' fields terminated by '|' INTO TABLE area(area_no,area_name,dhq)'"


#日志内容节选
YashanDB Loader Release 22.2.7.200 x86_64 c877471
Production on 2023-09-15 02:49:30.092

Table AREA:
column_name                                                        infile_column
AREA_NO                                                            1
AREA_NAME                                                          2
DHQ                                                                3


Table AREA:
  2 logical rows read.
  2 rows successfully loaded.
  0 rows not loaded due to data errors.
  0 rows not loaded because all fields were null.

Elapsed time was: 00:00:00.04

--- YashanDB Loader execution statistics ---
The degree of parallelism  : 2
The connection pool size   : 5
The number of reader       : 1
The number of binder       : 1

其他选项同开发手册LOAD DATA中对应选项描述。

# input_file_clause
syntax
INFILE input_file_path FIELDS file_type WITH EMBEDDED WITHOUT EMBEDDED FIELDS TERMINATED BY fields_terminated_char OPTIONALLY ENCLOSED BY enclosed_by_char
# OPTIONALLY ENCLOSED BY enclosed_by_char

指定导入数据的包围符，只可以指定为双引号，且指定时需要使用\符号进行转义，不指定时系统默认为按双引号包围。

其他语句同开发手册LOAD DATA中input_file_clause语句定义及描述。

# bad_file_clause
syntax
BADFILE bad_file_path

该语句用于指定导入文件的存放错误数据的地址，与input_file_clause语句指定的导入文件相关，其中写入错误数据条数受ERRORS参数限制，无论是否指定该语句，只要导入错误数据就会生成错误数据文件，省略则默认在导入文件目录下生成与导入文件同名，后缀为bad的数据文件，存在同名文件时会覆盖该文件。

支持相对路径及绝对路径，支持指定到目录及文件名，若指定到目录，则在指定目录下生成与导入文件同名，后缀为bad的数据文件，存在同名文件时会覆盖该文件。

错误数据不会被导入至数据库中，下述数据会被写入错误数据文件中：

  • 类型转换失败的数据。
  • 违反约束的数据。
  • 不符合CSV格式的数据。
  • 未命中分区的数据。

示例

#自行创建badfile.csv文件，文件位于/home/yasdb/loadexample目录中，文件内容为:
"1","2"
"nihao"
"hello"

#创建表bad_load
CREATE TABLE bad_load(c1 INT,c2 INT);

#执行导入命令
$ yasldr sales/sales@127.0.0.1:1688 batch_size=4032 control_text="'LOAD DATA OPTIONS(DEGREE_OF_PARALLELISM=3) INFILE '/home/yasdb/loadexample/badfile.csv' FIELDS TERMINATED BY ',' BADFILE '/home/yasdb/loadexample/badfile.bad' INSERT INTO TABLE bad_load(c1,c2)'"

#由于"nihao"和"hello"无法转换成int类型数据，如上两种数据会被记录在错误数据文件中，于终端中执行如下命令查看badfile.bad数据文件内容
$ cat badfile.bad
"nihao"
"hello"
# discard_file_clause
syntax
DISCARDFILE discard_file_path DISCARDS DISCARDMAX discard_number

该语句用于指定导入文件时过滤数据相关的属性。

# DISCARDFILE discard_file_path

该语句用于指定导入文件的存放过滤数据的地址，与input_file_clause语句指定的导入文件相关，可省略，省略则默认不创建过滤数据文件。如已指定了本语句，但导入数据不满足对应条件，仍不生成过滤数据文件。

支持相对路径及绝对路径，支持指定到目录及文件名，若指定到目录，则在指定目录下生成与导入文件同名，后缀为dsc的数据文件。

过滤数据不会被导入至数据库中，下述数据会被写入过滤数据文件中：

  • 整行映射均为NULL的数据。
# DISCARDS|DISCARDMAX discard_number

用于指定数据导入的过滤上限，当数据被过滤的数量达到上限时，终止数据导入，可省略，省略则默认为UINT64_MAX。

如未指定discard_file_path语句但指定了DISCARDS|DISCARDMAX关键字，将在导入文件目录下生成与导入文件同名，后缀为dsc的数据文件，存在同名文件时会覆盖该文件。

示例

#自行创建discardfile.csv，文件位于/home/yasdb/loadexample目录中，文件内容为:
"3","4"
"",""
""

#创建表discard_load
CREATE TABLE discard_load(c1 INT,c2 INT);

#执行导入命令
$ yasldr sales/sales@127.0.0.1:1688 batch_size=4032 control_text="'LOAD DATA OPTIONS(DEGREE_OF_PARALLELISM=3) INFILE '/home/yasdb/loadexample/discardfile.csv' FIELDS TERMINATED BY ',' DISCARDFILE '/home/yasdb/loadexample/discardfile.dsc' INSERT INTO TABLE discard_load(c1,c2)'"

#由于导入文件中的第二行数据均映射为NULL，该行数据会被记录在过滤数据文件中，于终端中执行如下命令查看discardfile.dsc数据文件内容
$ cat discardfile.dsc
"",""
# table_clause
syntax
load_type INTO TABLE schema . table_name when_clause TRAILING NULLCOLS column_clause directory_clause

该语句用于指定导入目标表的相关信息。

# when_clause

yasldr工具不支持执行本语句。

其他语句同开发手册LOAD DATA中table_clause语句定义及描述。

# column_clause
syntax
( normal_column_clause filler_column_clause lob_column_clause lls_column_clause , )

该语句用于指定目标表的列字段和导入模式，指定多个列字段以,分隔。

对于目标表中存在但未在数据加载中指定的列字段，系统自动补NULL值，因此对非空的列字段必须指定，否则数据加载无法成功。

Note：

该语句与LOAD DATA章节中的column_clause语句的语法和功能不同，仅适用于yasldr工具导入。

normal_column_clause

syntax
table_column_name COLUMN ( csv_column_order ) nullif_clause

该语句将导入模式指定为普通模式，将导入文件对应列的全部内容用于导入。

鉴于CSV格式文件存在数据大小限制，如需导入较大的数据文件，建议使用LLS模式进行部分导入或者LOBFILE模式进行全导入 。

其中：

  • table_column_clause为目标表已存在的列字段名称。
  • csv_column_order和nullif_clause语句同开发手册LOAD DATA中定义及描述。

示例

yasldr sales/sales@127.0.0.1:1688 batch_size=4032 control_text="'LOAD DATA OPTIONS (degree_of_parallelism=3) INFILE '?/csv/load_lls.csv' INTO TABLE sqlldr_lob(c1)'"

filler_column_clause

syntax
filler_column_name FILLER COLUMN ( csv_column_order )

该语句用于构造伪列，该伪列用于映射csv文件中的LOB文件地址数据，可被lob_column_clause语句引用。

其中：

  • filler_column_name为伪列的名称，建议与目标表中已存在列字段名称不同，否则可能导致导入错误。
  • csv_column_order语句同开发手册LOAD DATA中定义及描述。

lob_column_clause

syntax
table_column_name LOBFILE ( filler_column_name ) terminated_by_eof nullif_clause

该语句将导入模式指定为LOBFILE模式，该模式下通过引用FILLER伪列指向的LOB数据文件，将整个LOB文件导入至目标表指定的LOB列中。

其中：

  • table_column_clause为目标表已存在的LOB列字段名称。
  • filler_column_name为伪列名称。
  • csv_column_order和nullif_clause语句同开发手册LOAD DATA中定义及描述。
  • terminated_by_eof语句仅用于语法兼容，无实际含义。

Note：

filler_colomn_clause和lob_column_clause语句需配套使用，否则返回错误。

示例

yasldr sales/sales@127.0.0.1:1688 batch_size=4032 control_text="'LOAD DATA OPTIONS (degree_of_parallelism=3) INFILE '?/csv/load_lls.csv' INTO TABLE sqlldr_lob(c1,file1 filler,c2 lobfile(file1) terminated by eof)'"

lls_column_clause

syntax
table_column_name COLUMN ( csv_column_order ) nullif_clause LLS

该语句将导入模式指定为LLS（Lob Location Specifier）模式，通过指定LLS关键词选择该导入模式。该模式选取数据文件的部分内容或全部内容进行导入，且可指定从任意位置和任意长度开始导入。

其中：

  • table_column_clause为目标表已存在的列字段名称。
  • csv_column_order和nullif_clause语句同开发手册LOAD DATA中定义及描述。

指定了LLS关键字的目标表列字段映射的导入文件数据列格式需为filename.ext.nnn.mmm/：

  • filename.ext 为包含LOB数据的文件名称。
  • nnn 是文件中LOB数据的字节的偏移，仅允许为整数，且偏移量不允许超过LOB数据文件大小且不允许为负数。
    • 当输入偏移量的值为正数时，实际偏移量 = 输入值 - 1。
    • 值为0时，实际偏移量 = 0。
    • 值为负数时返回错误。
  • mmm 是字节中的LOB的长度，仅允许为整数。值为-1时表示null，为0时表示导入一个空LOB，不允许将其指定为小于-1的值。
  • 正斜杠（/）为终止字符，格式中必须包含该字符，否则报错。

示例

#自行于数据库中创建表sqlldr_lob(c1 int,c2 clob)

#load_lls.csv文件内容为：
LOB_FILE.dat.1.2/
LOB_FILE.dat.2.3/
#导入文件列数据为 LOB_FILE.dat.1.2/，意为从LOB_FILE.dat文件的偏移为0的位置为起始，截取长度为2的数据内容进行导入，正斜杠表示终止。
#导入文件列数据为 LOB_FILE.dat.2.3/，意为从LOB_FILE.dat文件的偏移为1的位置为起始，截取长度为3的数据内容进行导入，正斜杠表示终止。

#导入命令为：
yasldr sales/sales@127.0.0.1:1688 batch_size=4032 control_text="'LOAD DATA OPTIONS (degree_of_parallelism=3) INFILE '?/csv/load_lls.csv' INTO TABLE sqlldr_lob(c2 LLS)'"
# directory_clause

本语句用于指定对于run_level为split的时候拆分后的文件存放的目录，不指定的时候默认以infile的第一个文件所在的目录作为输出目录。

示例

#于/home/yasdb目录下创建file文件夹

#指定directory_clause
$ yasldr sales/sales@127.0.0.1:1688 batch_size=4032 control_text="'LOAD DATA OPTIONS(RUN_LEVEL=SPLIT,DEGREE_OF_PARALLELISM=2) INFILE '/home/yasdb/area.csv' FIELDS TERMINATED BY '|' OPTIONALLY ENCLOSED BY '\"' APPEND INTO TABLE area(area_no,area_name,dhq) directory '/home/yasdb/file''"

#result：拆分后的文件会存放在/home/yasdb/file目录中

#不指定directory_clause
$ yasldr sales/sales@127.0.0.1:1688 batch_size=4032 control_text="'LOAD DATA OPTIONS(RUN_LEVEL=SPLIT,DEGREE_OF_PARALLELISM=2) INFILE '/home/yasdb/area.csv' FIELDS TERMINATED BY '|' OPTIONALLY ENCLOSED BY '\"' APPEND INTO TABLE area(area_no,area_name,dhq) '"

#result：拆分后的文件会存放在/home/yasdb目录中

其他语句同开发手册LOAD DATA中table_clause语句定义及描述。

pdf-btn 下载文档
copy-btn 复制链接
段落导航
查看帮助
查看版本
命令格式
LOAD Options
LOAD Statement
指定方式
语句内容
option_clause
ENABLE_BULK
ERRORS
RUN_LEVEL
LOG
SILENT
STATS
input_file_clause
OPTIONALLY ENCLOSED BY enclosed_by_char
bad_file_clause
discard_file_clause
DISCARDFILE discard_file_path
DISCARDS|DISCARDMAX discard_number
table_clause
when_clause
column_clause
directory_clause