#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.执行分布式数据库导入时，用户至少是SELECT_CATALOG_ROLE角色：

GRANT select_catalog_role TO USER;

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

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

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;
GRANT SELECT ON sys.partobj$ TO USER;
GRANT SELECT ON sys.partcol$ TO USER;

Note：分布式数据库推荐使用yasboot工具进行拆分导入，有关yasboot工具的具体使用语法及限制可参考yasboot数据导入命令章节。

# LOAD Options

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

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

Note：

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

分布式复制表默认为BASIC方式导入，不支持BATCH方式导入，不支持ENABLE_DEDUP选项。

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

若用户未指定CONN_POOL_SIZE选项，则会根据用户在Load Statement中指定的DEGREE_OF_PARALLELISM进行自适应调整，调整方式为：
若DEGREE_OF_PARALLELISM > 30，则调整设置CONN_POOL_SIZE为15。

若DEGREE_OF_PARALLELISM > 10，则调整设置CONN_POOL_SIZE为10。

否则设置CONN_POOL_SIZE为默认值5。

# 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

# option_clause

语法图

代码

syntax

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

# ENABLE_BULK

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

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

# RUN_LEVEL

该选项用于指定程序执行的任务类型，设置后可指定任务类型为文件拆分任务；不设置时默认为数据导入任务，不会进行文件拆分操作。

SPLIT模式

本模式用于执行csv文件的拆分任务，不执行数据的导入。

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

Note：

为方便使用，YashanDB内置的yasboot工具可实现一键拆分csv文件和导入csv文件的功能，详情请参考数据导入命令章节。

需注意的是，yasboot工具要求执行导入的数据库实例已纳入yasom运维服务管理，否则需先进行数据库托管。

csv文件将按照分区键进行拆分，指定directory的情况下于指定路径中生成拆分后文件，未指定时于infile的第一个文件所在目录下生成拆分后文件。

示例

#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''"

SPLIT_TO_PART模式

本模式用于按照节点分区执行csv文件的拆分任务，不执行数据的导入。

文件生成路径：

单机部署中生成路径同SPLIT模式下生成路径。
分布式部署中拆分对象为非分区表时，生成路径同SPLIT模式下生成路径。
分布式部署中拆分对象为多分区表时，于directory指定路径或infile的第一个文件所在目录下生成以节点ip：端口号命名的文件夹，并于该文件夹中按照分区生成拆分文件。

# STATS

指定是否打印导入过程中的统计信息。值为TRUE时，会将导入过程中的统计信息输出至日志中；值为FALSE时，不会输出统计信息，输出的统计信息具体描述见统计信息。

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

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

# input_file_clause

语法图

代码

syntax

# OPTIONALLY ENCLOSED BY enclosed_by_char

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

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

# bad_file_clause

语法图

代码

syntax

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

# discard_file_clause

语法图

代码

syntax

# table_clause

语法图

代码

syntax

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

# when_clause

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

# trailing nullcols

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

# column_clause

column(csv_column_order)

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

nullif_clause

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

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

# directory_clause

本语句用于指定run_level选项拆分后的文件存放的目录，不指定的时候默认以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语句定义及描述。

# 导入详情介绍

# 导入前配置

yasldr工具在BATCH模式下执行导入时会通过批量绑定参数插入的方式直接与存储层数据结构对接，因此需要在导入前进行合理的参数配置，具体参数配置方式请参考开发手册LOAD DATA中导入环境准备部分。

# 导入

yasldr工具的导入过程为并行导入，会依据Load statements中设置的DEGREE_OF_PARALLELISM参数值开启多个线程进行并行导入。

导入过程中涉及的线程分为三类：

yasldr主线程：负责Load Options和Load Statement的解析，将待导入的CSV数据文件进行大粒度切分，启动READER线程和BINDER线程进行数据导入。
READER线程：负责将主线程切分后的csv数据文件读取到内存中，供BINDER线程解析。
BINDER线程：负责逐行解析内存中的数据，按照表字段类型对数据进行转换，构造BUF数组和INDICATOR数组，获取连接后，调用C驱动接口发送到服务端，接收并解析服务端返回的错误数据信息。

# 导入日志

导入执行结束后，会显示诸如Check /home/yasdb/area_stats.log for more info.的日志路径信息，该信息中显示的日志打印了本次导入的目标表名、表字段和csv数据列的映射关系、错误数据的位置以及错误原因等信息。

示例

YashanDB Loader Enterprise Edition Debug 23.1.0.2 x86_64 a533f66
Production on 2023-10-13 11:06:58.212

Table AREA:
column_name                                                        infile_column
AREA_NO                                                            1
AREA_NAME                                                          2
DHQ                                                                3

infile /home/yasdb/area_stats.csv offset 1 is rejected by table AREA because
type convert error : not a valid number.

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

# 统计信息

若导入时打开了STATS选项，则导入结束后日志中会包含本次导入过程中的执行统计情况，输出的统计信息包含：

概述

READER、BINDER线程及CONN连接的数量。

READER线程

读取文件数据（Total IO）：IO次数，总用时，最长IO时间，最短IO时间，平均IO时间，单位微秒。
生成文件buffer（Total buffer）：个数，最大buffer大小，最小buffer大小，平均buffer大小，单位字节。
生成buffer速度（The processing buffer rate）：单位MB/s。
生成单个buffer时间（The processing per buffer）：单位毫秒。

BINDER线程

读取数据时间（The fetching line）：行数，总用时，读取单行最长时间，最短时间，平均时间，单位微秒。
读取数据大小（The line size）：最长行大小，最短行大小，平均行大小，单位字节。
构造数据时间（The setting row）：行数，总用时，构造单行最长时间，最短时间，平均时间，单位微秒。
批量插入时间（The batch insert）：次数，总用时，单次批量插入最长时间，最短时间，平均时间，单位微秒。
等待连接时间（The waiting conn）：次数，总用时，等待最长时间，最短时间，平均时间，单位微秒。
使用连接时间（The using conn）：次数，总用时，使用最长时间，最短时间，平均时间，单位微秒。
构造OUTLINE LOB时间（The setting lob）：行数，总用时，构造单行所有LOB列最长时间，最短时间，平均时间，单位微秒。
构造OUTLINE LOB大小（The outline lob size）：构造单行所有LOB列总大小，最长大小，最短大小，平均大小，单位字节。
构造OUTLINE LOB速度（The setting lob rate）：单位MB/s。
构造单行OUTLINE LOB时间（The setting per lob）：单位毫秒。

CONN连接

执行COMMIT时间（Total commit）：次数，总用时，单次执行最长时间，最短时间，平均时间，单位微秒。
CONN连接单次COMMIT时间（Per commit time）：单位毫秒。
发送数据时间（Total send row）：行数，总用时，单次发送最长时间，最短时间，平均时间，单位微秒。

总结

READER线程生成文件buffer（Total buffer）：总个数，最大buffer大小，最小buffer大小，平均buffer大小，单位字节。
READER线程生成buffer速度（The processing buffer rate）：单位MB/s。
READER线程生成单个buffer时间（The processing per buffer）：单位毫秒。
BINDER线程构造数据时间（Total rows set）：总行数，总用时，构造单行最长时间，最短时间，平均时间，单位微秒。
BINDER线程批量插入时间（Total batch insert）：总次数，总用时，单次批量插入最长时间，最短时间，平均时间，单位微秒。
BINDER线程构造OUTLINE LOB时间（Total setting lob）：总行数，总用时，构造单行所有LOB列最长时间，最短时间，平均时间，单位微秒。
BINDER线程构造OUTLINE LOB大小（Total outline lob size）：构造单行所有LOB列总大小，最长大小，最短大小，平均大小，单位字节。
BINDER线程构造OUTLINE LOB速度（The setting lob rate）：单位MB/s。
BINDER线程构造单行OUTLINE LOB时间（The setting per lob）：单位毫秒。
BINDER线程等待连接时间（Total waiting conn）：总次数，总用时，等待最长时间，最短时间，平均时间，单位微秒。
CONN连接执行COMMIT时间（Total commit）：总次数，总用时，单次执行最长时间，最短时间，平均时间，单位微秒。
CONN连接单次COMMIT时间（Per commit time）：单位毫秒。
CONN连接发送数据时间（Total send row）：总行数，总用时，单次发送最长时间，最短时间，单位微秒。
解析导入语句时间（The parse time）：单位微秒。
处理表信息时间（The prepare time）：单位微秒。
建立连接时间（The connect time）：单位微秒。
最后一次commit时间（The last commit time）：单位微秒。
释放连接时间（The free connection time）：单位微秒。
不同阶段时间占比及处理速度：以CPU TIME计算，包括读数据时间（READ），解析构造数据时间（DECODE），发送数据批量插入时间（SEND），等待连接时间（WAIT），其他时间不做划分（OTHERS）。

示例

#area_stats.csv文件内容为:
8|load|801|loadbranch|8
9|load|901|loadbranch|9

#area创建语句
CREATE TABLE area(
area_no   INTEGER,
area_name VARCHAR(10),
dhq       INTEGER);

$ 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 '|' OPTIONALLY ENCLOSED BY '\"' APPEND INTO TABLE area(area_no,area_name,dhq)'"

#统计信息节选
--- YashanDB Loader execution statistics ---
The degree of parallelism  : 2
The connection pool size   : 5
The number of reader       : 1
The number of binder       : 1

Reader statistics: (thread 0)
Total IO counts            : 1
Total IO time              : 14 (μs)
The longest IO time        : 14 (μs)
The shortest IO time       : 14 (μs)
The average IO time        : 14 (μs)
Total buffer counts        : 1
The biggest buffer size    : 48 (B)
The smallest buffer size   : 48 (B)
The average buffer size    : 48(B)
The processing buffer rate : 3.27 (MB/s)
The processing per buffer  : 0.01 (ms)

Binder statistics: (thread 0)
The fetching line counts   : 2
The fetching line time     : 1 (μs)
The longest fetch time     : 1 (μs)
The shortest fetch time    : 0 (μs)
The average fetch time     : 0 (μs)
The longest line size      : 24 (B)
The shortest line size     : 24 (B)
The average line size      : 24 (B)
The setting row counts     : 2
The setting row time       : 2 (μs)
The longest set time       : 2 (μs)
The shortest set time      : 0 (μs)
The average set time       : 1 (μs)
The batch insert counts    : 1
The insert time            : 1117 (μs)
The longest insert time    : 1117 (μs)
The shortest insert time   : 1117 (μs)
The average insert time    : 1117 (μs)
The waiting conn counts    : 1
The waiting conn time      : 0 (μs)
The longest waiting time   : 0 (μs)
The shortest waiting time  : 0 (μs)
The average waiting time   : 0 (μs)
The using conn counts      : 1
The using conn time        : 1117 (μs)
The longest using time     : 1117 (μs)
The shortest using time    : 1117 (μs)
The average using time     : 1117 (μs)

Connection statistics: (conn 0)
Total commit counts        : 1
Total commit time          : 360 (μs)
The longest commit time    : 360 (μs)
The shortest commit time   : 360 (μs)
The average commit time    : 360 (μs)
Per commit time            : 0.36 (ms)
Total send row counts      : 1
Total send row time        : 1117 (μs)
The longest send row time  : 1117 (μs)
The shortest send row time : 1117 (μs)

Table statistics: (AREA)
Total buffer counts        : 1
The biggest buffer size    : 48 (B)
The smallest buffer size   : 48 (B)
The average buffer size    : 48 (B)
The processing buffer rate : 3.27 (MB/s)
The processing per buffer  : 0.01 (ms)

Total rows set             : 2
Total set time             : 2 (μs)
The longest set time       : 2 (μs)
The shortest set time      : 0 (μs)
The average set time       : 1 (μs)
Total batch insert counts  : 1
Total insert time          : 1117 (μs)
The longest insert time    : 1117 (μs)
The shortest insert time   : 1117 (μs)
The average insert time    : 1117 (μs)
Total waiting conn counts  : 1
Total waiting conn time    : 0 (μs)
The longest waiting time   : 0 (μs)
The shortest waiting time  : 0 (μs)
The average waiting time   : 0 (μs)

Total commit counts        : 5
Total commit time          : 916 (μs)
The longest commit time    : 360 (μs)
The shortest commit time   : 131 (μs)
The average commit time    : 183 (μs)
Per commit time            : 0.18 (ms)
Total send row counts      : 1
Total send row time        : 1117 (μs)
The longest send row time  : 1117 (μs)
The shortest send row time : 1117 (μs)

The parse time             : 1466 (μs)
The prepare time           : 12717 (μs)
The connect time           : 1823 (μs)
The last commit time       : 919 (μs)
The free connection time   : 83104 (μs)

The following is different phase information:
 PHASE               RATE(MB/s)            RATE(kRows/s)                TIME(μs)               PERCENTAGE
  READ                     3.27                   142.86                       14                     0.01%
DECODE                    22.89                  1000.00                        2                     0.00%
  SEND                     0.04                     1.79                     1117                     0.48%
  WAIT                                                                          0                     0.00%
OTHERS                                                                     231079                    99.51%

# 导入结果验证

导入结束后，可以对结果进行验证，检查数据是否全部正确导入。

可以通过对比CSV文件中的数据条数和数据库表中的数据条数是否一致来进行验证。

示例

#area_stats.csv文件内容为:
8|load|801|loadbranch|8
9|load|901|loadbranch|9

#area创建语句
CREATE TABLE area(
area_no   INTEGER,
area_name VARCHAR(10),
dhq       INTEGER);

$ 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 '|' OPTIONALLY ENCLOSED BY '\"' APPEND INTO TABLE area(area_no,area_name,dhq)'"
YashanDB Loader Enterprise Edition Debug 23.1.0.2 x86_64 a533f66
2 rows successfully loaded.
Check /home/yasdb/area_stats.log for more info.
[YASLDR] execute succeeded

#计算文件中的数据条数
$ wc -l area_stats.csv
2 area_stats.csv

#查询数据库表中的数据条数是否和文件条数一致
$ yasql sales/sales@127.0.0.1:1688 -c "select count(*) from area"

             COUNT(*)
---------------------
                    2

# 常见问题

1.导入结束后显示[YASLDR] execute succeeded with info而非[YASLDR] execute succeeded。

yasldr工具默认开启容错特性，以便跳过错误数据继续执行导入。若导入结束后显示[YASLDR] execute succeeded with info，说明导入过程中遇到了错误数据，请检查提示的日志文件进行确认。

2.导入过程中报错显示no free cursors in cursor pool。

该问题可能出现在分布式导入场景，请使用yasboot工具进行导入。

#yasldr使用指导

# 查看帮助

# 查看版本

# 命令格式

# LOAD Options

# LOAD Statement

# 指定方式

# 语句内容

# option_clause

# ENABLE_BULK

# RUN_LEVEL

# STATS

# input_file_clause

# OPTIONALLY ENCLOSED BY enclosed_by_char

# bad_file_clause

# discard_file_clause

# table_clause

# when_clause

# trailing nullcols

# column_clause

# directory_clause

# 导入详情介绍

# 导入前配置

# 导入

# 导入日志

# 统计信息

# 导入结果验证

# 常见问题

段落导航