search-icon search-icon

#yasldr使用指导

# 查看帮助

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

$ yasldr -H
YashanDB Loader Enterprise Edition Release 23.2.0.25 x86_64 431125c

YashanDB LOADER HELP:
To specify parameters, should use keywords:
  Command Format:
    YASLDR USERNAME/PASSWORD@IP:PORT KEYWORD=value

    "USERNAME/PASSWORD@URL" must be the first on the command line, "@URL" default 127.0.0.1:1688
    KEYWORD                    DESCRIPTION (DEFAULT)
    ---------------------------------------------------------------------------------------------------
    BATCH_SIZE                 the number of lines per batch, default 4032, range [1, 65535]
    CONTROL_FILE               a file containing the LOAD statement
    CONTROL_TEXT               the LOAD statement, only be used when CONTROL_FILE is not specified
    MODE                       import mode, including BASIC/BATCH, default BATCH
    PACKET_SIZE                client expected packet size, default 128KB, range [65536, 524288]
    CONN_POOL_SIZE             client connection pool size, default 5, range [1, 32]
    SENDERS                    the number of sender thread, default 1, range [1, 128]
    CSV_CHUNK_SIZE             the size of file segmentation, default 128, range [16, 4096), unit MB
    INLINE_BLOB_FORMAT         the data format of blob column in csv file, including BINARY/STRING, default BINARY
    PROGRESS                   the mode of import progress display, including NULL/DETAIL default NULL
    LOG_PATH                   the directory to write the log file
    LOG_LEVEL                  the mode of log level, default INFO, range [off, error, warn, info, debug, trace]
    SLICE_POLICY               the file segment alloc policy, including SEQUENCE/RANDOM, default SEQUENCE
    DATE_FORMAT                the csv date format, default yyyy-mm-dd hh24:mi:ss
    TIME_FORMAT                the csv time format, default hh24:mi:ss.ff
    TIMESTAMP_FORMAT           the csv timestamp format, default yyyy-mm-dd hh24:mi:ss.ff
    CSV_LINE_SIZE              the max line size, default 126, range [1, 1048576], unit KB
    GIS_SRID                   the srid filed for st_geometry column, default 0, range [0, INT_MAX]
    CHARACTER_SET              set data file character set, range [ASCII, GBK, UTF8, ISO88591, GB18030], default the same as client character set
    MAX_MEM_SIZE               set the max memory usage, default 1, range [1, 1024], unit GB\n
    BIT_FORMAT                 set the bit columns data format, default BINARY, range [BINARY, DECIMAL]

  Example:
    YASLDR USERNAME/PASSWORD@IP:PORT CONTROL_FILE=LOAD.CTL

# 查看版本

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

$ yasldr -V
YashanDB Loader Enterprise Edition Release 23.2.0.25 x86_64 431125c

# 导入指令格式

$ YASLDR USERNAME/PASSWORD@IP:PORT {LOAD OPTIONS} {LOAD STATEMENT}

USERNAME/PASSWORD@IP:PORT

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

对该用户的权限要求为：

  • 对待导入数据的目标表应具备写权限和查询权限。

  • 在分布式部署中，用户还应至少为SELECT_CATALOG_ROLE角色并具备ROUTE$，NODE_INFO$，DIST$，OBJ$，DISTCOL$，TAB$，USER$，PARTOBJ$以及PARTCOL$系统表权限。

-- 为用户授权SELECT_CATALOG_ROLE角色
GRANT select_catalog_role TO 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;
GRANT SELECT ON sys.partobj$ TO USER;
GRANT SELECT ON sys.partcol$ TO USER;

# LOAD OPTIONS

LOAD OPTIONS部分用来设置运行yasldr的命令行参数。

yasldr提供多个可选的命令行控制参数，方便用户调整和设置导入过程。用户在执行导入命令时，可以同时设置多个参数，例如：

  • BATCH_SIZE：导入过程中每批次发送的CSV数据行数。
  • MODE：导入方式，可以指定BASIC方式导入或BATCH导入方式。

更多命令行参数的描述见yasldr命令行参数。

# 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下对双引号需使用\转义。

# 语句内容

# 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 , )

该语句用于指定加载操作的相关选项，下列是一些常使用的参数：

# COMMIT_ROWS

决定事务的提交频率，假设其值为n，解码数据文件中n条数据，提交一次事务，BULKLOAD导入例外。

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

# DEGREE_OF_PARALLELISM

指定数据加载任务的并行度，受目标端数据库参数MAX_PARALLEL_WORKERS限制，若degree_number大于该参数，以该参数为准。

parameter_value须为一个范围在[2,256]之间的整数，默认值为8。系统会结合该参数值、硬件环境、数据文件大小等计算实际的并行度值，并使加载任务按实际值并发运行。

# ERRORS

指定数据导入的容错数据条数上限，当数据错误条数达到上限时，终止数据导入。多个文件导入时，错误数据条数累加计算。

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

更多详细参数描述见yasldr参数说明。

# 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

该语句指定导入文件的相关信息。可同时指定多个导入文件，以空格分隔。

支持使用*和?通配符进行文件名称的正则匹配，*用于匹配0个或任意多个字符，?用于匹配单个字符（即占位一个字符）。具体匹配规则如下：

  • 若INFILE指定的文件与通配符匹配的文件重名，则会报重名错误。
  • 若匹配到目录，则直接跳过，不会递归处理。
  • 单次最多匹配250个文件，若匹配的文件数超过上限，则会报错。

示例

#导入/home/yasdb目录下以.csv结尾的所有文件
$ yasldr sales/sales@127.0.0.1:1688 control_text="'LOAD DATA INFILE '/home/yasdb/*.csv' FIELDS TERMINATED BY '|' OPTIONALLY ENCLOSED BY '\"' APPEND INTO TABLE area(area_no,area_name,dhq)'"

#导入/home/yasdb目录下csv10-csv20之间的所有文件
$ yasldr sales/sales@127.0.0.1:1688 control_text="'LOAD DATA INFILE '/home/yasdb/csv1?.csv' FIELDS TERMINATED BY '|' OPTIONALLY ENCLOSED BY '\"' APPEND INTO TABLE area(area_no,area_name,dhq)'"
# INFILE input_file_path

导入文件的路径及名称，支持指定绝对和相对路径。

该语句指定的导入文件必须存在，且系统用户必须拥有对其的读取权限，否则加载任务报错退出。

可以指定一个空数据文件，不影响加载任务的继续运行。

# FIELDS file_type

该语句用于指定导入文件的类型，可省略，省略则默认为CSV文件。

file_type的值只可以为CSV，否则加载任务报错退出。

# WITH EMBEDDED|WITHOUT EMBEDDED

该语句用于指定换行符是否可被包围符包围作为数据，可省略，省略则默认为WITHOUT EMBEDDED，即换行符不可作为数据。

# FIELDS TERMINATED BY fields_terminated_char

该语句用于指定导入数据列的分隔符，不指定时默认将逗号作为分隔符。

fields_terminated_char支持以下表示方法：

  • 单字节字符
  • 十六进制
  • 整数

取值范围：ASCII码1-126对应的字符，数字、换行符、大小写字母除外。

# OPTIONALLY ENCLOSED BY enclosed_by_char

该语句用于指定导入数据的包围符，可省略，省略时系统默认为按双引号包围。

enclosed_by_char支持以下表示方法：

  • 单字节字符
  • 十六进制
  • 整数

取值范围：ASCII码1-126对应的字符，换行符、空格除外。

Note：

  • 包围符与分隔符不能相同。
  • 指定分隔符或包围符时，双引号应转义为 \"，单引号应转义为 ''，反单引号应转义为 \`。
  • 指定分隔符为空格时，不支持字符表示，应使用十六进制或整数表示。
# bad_file_clause
syntax
BADFILE bad_file_path

该语句用于指定错误数据文件的地址，可省略，省略则默认在input_file_clause语句指定的导入文件目录下生成与导入文件同名但后缀为bad的数据文件，若存在同名文件将会直接覆盖。

无论是否指定本语句，只要导入错误数据就会生成相应的错误数据文件，该文件中可写入的错误数据条数受ERRORS参数限制。

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

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

示例

#准备本地CSV文件（以/home/yasdb/area.csv为例）
$ vi /home/yasdb/area.csv
  "1"|"1"
  "nihao"
  "hello"

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

#执行导入命令
$ yasldr sales/sales@127.0.0.1:1688 control_text="'LOAD DATA INFILE '/home/yasdb/area.csv' FIELDS TERMINATED BY '|' OPTIONALLY ENCLOSED BY '\"' BADFILE '/home/yasdb/area.bad' INSERT INTO TABLE bad_load(c1,c2)'"

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

该语句用于指定存放过滤数据的地址，与input_file_clause语句指定的导入文件相关，可省略，省略则默认不创建过滤数据文件。

即使指定该语句，仍需导入数据满足过滤条件才会生成相应的过滤数据文件，过滤数据不会被导入至数据库中。

过滤条件如下：

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

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

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

# table_clause
syntax
load_type INTO TABLE schema . table_name TRAILING NULLCOLS column_clause directory_clause

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

# TRAILING NULLCOLS

当导入文件中的数据列少于目标表的列数时，指定TRAILING NULLCOLS可以对缺少映射数据的列补NULL值（如果该列上存在一些不允许NULL值的约束定义，补NULL值仍会导致错误），否则加载任务将报错。

当导入文件中的数据列多于目标表的列数时，多余的数据列会被自动忽略且不会抛出错误，这种行为与trailing nullcols配置参数无关。

# column_clause
syntax
( table_column_name filler_column_clause lob_column_clause lls_column_clause , )

filler_column_clause

syntax
filler_column_name FILLER

Note：

允许存在未被引用的FILLER伪列，但建议配套使用filler_colomn_clause和lob_column_clause语句。

lob_column_clause

syntax
table_column_name LOBFILE ( filler_column_name ) terminated_by_eof

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

lls_column_clause

syntax
table_column_name LLS

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

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

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

示例

#准备本地lob1.dat和lob2.dat文件，文件位于/home/yasdb/，内容均为：
abcdefg

#创建/home/yasdb/load_lob.csv文件，内容为：
"1"|"lob1.dat"|"lob1.dat.1.7/"

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

#执行导入指令
$ yasldr sales/sales@127.0.0.1:1688 batch_size=4032 control_text="'LOAD DATA INFILE '/home/yasdb/load_lob.csv' FIELDS TERMINATED BY '|' OPTIONALLY ENCLOSED BY '\"' INTO TABLE sqlldr_lob(c1,file1 filler,c2 lobfile(file1), c3 LLS)'"
# 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目录中

# 导入详情介绍

# 导入前配置

yasldr工具在BATCH模式下执行导入时会通过批量绑定参数插入的方式直接与存储层数据结构对接，为提升性能，需要在导入前对目标端数据库的一些参数进行合理的配置，具体参数配置如下：

配置参数项 建议操
LARGE_POOL_SIZE 调整为参数允许范围内的最大值，若导入过程出现no free blocks in large pool错误，表示该值仍不能满足导入资源要求，解决方案：
1. 调整导入表，减少导入heap分区表的分区总个数
2. 降低导入时的degree_of_parallelism参数
3. 重新导入
WORK_AREA_STACK_SIZE reader线程数 = degree_of_parallelism / (decoder_thread_times + 1)，向上取整
sender线程数 = degree_of_parallelism - reader线程数
SIZE = 512KB + 126KB * 表个数 * sender线程数
WORK_AREA_POOL_SIZE MIN_SIZE = 线程数量 * 表数量 * 分区数量 * 256B + reader线程数 * sender线程数 * 1KB
DATA_BUFFER_SIZE 指定数据缓存区的大小。数据缓存区容量越大，导入性能越好，默认值为64M，取值范围为[32M,64T]
COLUMNAR_VM_BUFFER_SIZE 当LSC表以BULKLOAD模式导入时，建议调大此参数，可以增加计算性能，默认值为2G，取值范围为[128M,2T]
SCOL_DATA_BUFFER_SIZE 指定LSC存储引擎使用的数据缓存区的大小，当LSC表以BULKLOAD模式导入时，此参数配置值越大，导入性能越好，默认值为128M，取值范围为[128M,2T]

# 导入

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

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

  • CONTROLLER线程：即主线程，负责Load Options和Load Statement的解析，将待导入的CSV数据文件进行切分，启动READER线程和SENDER线程进行数据导入。

  • READER线程：负责读取和解析CSV文件，对数据进行解码，并按照分区组织数据后，将数据交给SENDER线程发送。

  • SENDER线程：负责将READER线程提交的数据发送到服务端，并解析处理服务端返回的消息。

# 导入日志

导入执行结束后，会显示诸如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选项，则导入结束后日志中会包含本次导入过程中的执行统计情况，输出的统计信息包含：

概述

统计信息分为CONTROLLER的统计信息、READER统计信息、SENDER统计信息，在分布式情况下，还存在NODE统计信息。

CONTROLLER统计信息

CONTROLLER部分展示READER和SENDER线程的数量、解析耗时和准备执行环境的耗时。

READER统计信息

READER统计信息部分展示IO次数、IO耗时、解码的行数、行最大宽度、行平均宽度、读取行的总耗时、解码总耗时、分区计算总耗时、转换总耗时、等待分区可用总耗时、发送队列总耗时以及线程的总运行耗时。

SENDER统计信息

SENDER统计信息部分展示发送次数、发送总耗时、单次最大发送耗时、执行提交的次数、提交的总耗时、获取发送单元的总耗时、转换总耗时以及线程总运行耗时。

NODE统计信息

NODE统计信息部分展示发送到节点的行数、发送的次数、发送总耗时、单次最大发送耗时、提交次数、提交总耗时和节点的地址信息。

示例

#area_stats.csv文件内容为:
1|load|101|loadbranch|1
2|load|201|loadbranch|2
3|load|301|loadbranch|3
4|load|401|loadbranch|4
5|load|501|loadbranch|5
6|load|601|loadbranch|6

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

#执行后统计信息示例
Reader Execution Statistics:
   id    io_cnt     io_cost    avg_cost     lines   max_len   min_len   avg_len  fetch_cost  decode_cost locate_cost  to_row_cost    wait_cost   enque_cost      elapsed
    0         1           6           6         6        24        24        24           2            8           5            4            0            0         2758

Sender Execution Statistics:
   id    send_cnt   send_cost    max_cost  commit_cnt commit_cost  deque_cost to_col_cost     elapsed
    0           6        1307         353           3         748           2          12       13107

Node Send Statistics:
   id       lines    send_cnt   send_cost    max_cost  commit_cnt commit_cost                       address
    0           1           1         352         352           1         293            xxx.xxx.xxx.xxx:xxxx
    1           3           3         521         344           1         214            xxx.xxx.xxx.xxx:xxxx
    2           2           2         431         325           1         241            xxx.xxx.xxx.xxx:xxxx

# 导入结果验证

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

可以通过对比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
pdf-btn 下载文档
copy-btn 复制链接
段落导航
查看帮助
查看版本
导入指令格式
LOAD OPTIONS
LOAD STATEMENT
指定方式
语句内容
load data
option_clause
COMMIT_ROWS
DEGREE_OF_PARALLELISM
ERRORS
input_file_clause
INFILE input_file_path
FIELDS file_type
WITH EMBEDDED|WITHOUT EMBEDDED
FIELDS TERMINATED BY fields_terminated_char
OPTIONALLY ENCLOSED BY enclosed_by_char
bad_file_clause
discard_file_clause
(DISCARDS|DISCARDMAX) discard_number
table_clause
TRAILING NULLCOLS
column_clause
directory_clause
导入详情介绍
导入前配置
导入
导入日志
统计信息
导入结果验证