此文档主要介绍 TuGraph 的数据导入功能。其中包括 CSV 格式的分隔符，jsonline 的格式示例，以及导入在线和离线的两种模式。
在图数据库服务安装成功后，您可以使用lgraph_import批量导入工具将现有数据导入 TuGraph。lgraph_import支持从 CSV 文件和 JSON 数据源导入数据。
CSV 格式
[movies.csv]
id, name, year, rating
tt0188766,King of Comedy,1999,7.3
tt0286112,Shaolin Soccer,2001,7.3
tt4701660,The Mermaid,2016,6.3
jsonline 格式
["tt0188766","King of Comedy",1999,7.3]
["tt0286112","Shaolin Soccer",2001,7.3]
["tt4701660","The Mermaid",2016,6.3]TuGraph 支持两种导入模式：
- 离线模式：读取数据并将其导入指定服务器的数据文件，应仅在服务器离线时完成。
- 在线模式：读取数据并将其发送到工作中的服务器，然后将数据导入其数据库。
CSV格式的分隔符可以是单字符或多字符组成的字符串，其中不能包含`\r`或`\n`。注意不同的shell会对输入字符串做不同的处理，因此针对不同的shell输入参数可能需要不同的转义处理。
此外，lgraph_import还支持以下转义字符，以便输入特殊符号：
| 转义符 | 说明 |
|---|---|
| \ | 反斜杠\\ |
| \a | 响铃，即 ASCII 码 0x07 |
| \f | form-feed，即 ASCII 码 0x0c |
| \t | 水平制表符，即 ASCII 码 0x09 |
| \v | 垂直制表符，即 ASCII 码 0x0b |
| \xnn | 两位十六进制数，表示一个字节，如\x9A |
| \nnn | 三位八进制数，表示一个字节，如\001, \443，数值范围不能超过 255 |
例：
$ ./lgraph_import -c ./import.config --delimiter "\001\002"lgraph_import工具通过指定的配置文件进行环境配置。配置文件描述输入文件的路径、它们所代表的点/边以及点/边的格式。
配置文件包含两部分：schema 和 files。schema部分定义 label，files部分描述要导入的数据文件。
- schema (数组形式）
- label（必选，字符串形式）
- type（必选，值只能是 VERTEX 或者 EDGE）
- properties（数组形式，对于点必选，对于边如果没有属性可以不配置）
- name（必选，字符串形式）
- type （必选，BOOL，INT8，INT16，INT32，INT64，DATE，DATETIME，FLOAT，DOUBLE，STRING，BLOB）
- optional（可选，代表该字段可以配置，也可以不配置）
- index（可选，该字段是否需要建索引）
- unique（可选，该字段是否建索引，并且是 unique 类型的，即全局唯一）
- pair_unique（可选，该字段是否建索引，并且是 pari_unique 类型的，即两点间唯一，仅用于边索引）unique与pair_unique只能设置一个，同时设置并运行将会因为输入异常而终止
- primary (仅点配置，必选，主键字段，需指定一个 property，用来唯一确定一个点)
- temproal (仅边配置，可选，指定时间戳属性用于存储层排序)
- temporal_field_order (仅边配置，可选，默认为"ASC"，表示升序，也可配置为"DESC"，表示降序)
- constraints (仅边配置，可选，数组形式，起点和终点的 label，不配置或者为空代表不限制)
- detach_property (点边都可配置，可选，默认是
false。true代表属性数据单独存放，在内存不够，属性数据比较多的场景下可以减少io读放大)
- files （数组形式）
- path（必选，字符串，可以是文件路径或者目录的路径，如果是目录会导入此目录下的所有文件，需要保证有相同的 schema）
- header（可选，数字，头信息占文件起始的几行，没有就是 0）
- format（必须选，只能是 JSON 或者 CSV）
- label（必选，字符串）
- columns（数组形式）
- SRC_ID (特殊字符串，仅边有，代表这列是起始点数据)
- DST_ID (特殊字符串，仅边有，代表这列是目的点数据)
- SKIP (特殊字符串，代表跳过这列数据)
- [property]
- SRC_ID (仅边配置，值是起始点标签)
- DST_ID (仅边配置，值是目的点标签)
因为TuGraph对key的长度有限制，唯一索引不允许建立超过限制长度的索引，而非唯一索引会对超过长度限制的属性进行截断处理，并且在通过迭代器遍历非唯一索引时，拿到的key也是经过截断的，可能和预期不一致。针对不同类型的非唯一索引，截断长度是不同的。
unique索引是全局唯一的，该索引key的最大长度是480bytes。primary作为特殊的unique索引，因此最大key的长度也是480bytes，超过无法建立索引。
pair_unique索引是指两点间唯一的索引，这种类型的索引只能创建于边的schema中，这种索引在用户指定的key后面加上了源点和目标点的vid，每个vid是5bytes长度。因此最大key的长度是470bytes，超过无法建立索引。
非唯一索引是指既没有设置unique为1，也没有设置pair_unique为1的索引，在TuGraph的实现中，此类索引一个key可能映射到多个值，为了加速查找和写入，在用户指定的key后面加上了一组vid或euid中的最大值。其中对于创建于点中的非唯一索引，key后面跟着vid，每个vid是5bytes长度，因此最大长度是475bytes。 对于创建于边中的非唯一索引，key后面跟着euid，每个euid是24bytes长度，因此最大长度是456bytes。索引key超过对应长度则会自动截断。
{
"schema": [
{
"label": "actor",
"type": "VERTEX",
"properties": [
{ "name": "aid", "type": "STRING" },
{ "name": "name", "type": "STRING" }
],
"primary": "aid"
},
{
"label": "movie",
"type": "VERTEX",
"properties": [
{ "name": "mid", "type": "STRING" },
{ "name": "name", "type": "STRING" },
{ "name": "year", "type": "INT16" },
{ "name": "rate", "type": "FLOAT", "optional": true }
],
"primary": "mid",
"detach_property": false
},
{
"label": "play_in",
"type": "EDGE",
"properties": [{ "name": "role", "type": "STRING", "optional": true }],
"constraints": [["actor", "movie"]]
}
],
"files": [
{
"path": "actors.csv",
"header": 2,
"format": "CSV",
"label": "actor",
"columns": ["aid", "name"]
},
{
"path": "movies.csv",
"header": 2,
"format": "CSV",
"label": "movie",
"columns": ["mid", "name", "year", "rate"]
},
{
"path": "roles.csv",
"header": 2,
"format": "CSV",
"label": "play_in",
"SRC_ID": "actor",
"DST_ID": "movie",
"columns": ["SRC_ID", "role", "DST_ID"]
}
]
}对于上述配置文件，定义了三个 label：两个点类型actor和movie，一个边类型role。每个 label 都描述了：label 的名字、类型（点还是边）、属性字段有哪些以及每个字段的类型。对于点，另外定义了 primary 字段是哪个；对于边，另外定义了 constraints 字段，用来限制边的起点和终点只能是哪些组合。
还描述了三个数据文件，两个点的数据文件actors.csv和movies.csv，一个边的数据文件roles.csv。每个部分都描述了：文件的路径（path）、数据类型（format）、信息头占开头几行（header）、是哪个 label 的数据（label）、文件中每行数据中的每个列对应的字段是哪个。
对于上述配置文件，import 工具在执行的过程中会先在 TuGraph 中创建actor、movie、role这三个 label，然后再执行三个文件的数据导入。
离线模式只能在离线状态的服务器使用。离线导入会创建一张新图，因此更适合新安装的 TuGraph 服务器上的第一次数据导入。
要在离线模式下使用lgraph_import工具，可以指定lgraph_import --online false选项。要了解可用的命令行选项，请使用lgraph_import --online false --help：
$ ./lgraph_import --online false -help
Available command line options:
--log Log file to use, empty means stderr. Default="".
-v, --verbose Verbose level to use, higher means more verbose.
Default=1.
...
-h, --help Print this help message. Default=0.命令行参数：
- -c, --config_file
config_file: 导入配置文件名，其格式要求见下述。 - --log
log_dir: 日志目录。默认为空字符串，此时将日志信息输出到控制台。 - --verbose
0/1/2: 日志等级，等级越高输出信息越详细。默认为 1。 - -i, --continue_on_error
true/false: 在碰到错误时跳过错误并继续，默认为 false，碰到错误立即退出。 - -d, --dir
{diretory}: 数据库目录，导入工具会将数据写到这个目录。默认为./db。 - --delimiter
{delimiter}: 数据文件分隔符。只在数据源是 CSV 格式时使用，默认为","。 - -u, --username
{user}: 数据库用户名。需要是管理员用户才能执行离线导入。 - -p, --password
{password}: 指定的数据库用户的密码 - --overwrite
true/false: 是否覆盖数据。设为 true 时，如果数据目录已经存在，则覆盖数据。默认为false。 - -g, --graph
{graph_name}: 指定需要导入的图种类。 - -h, --help: 输出帮助信息。
在这个例子中，我们使用上面描述的电影-演员数据来演示导入工具的使用方法。待导入数据分为三个文件：movies.csv，actors.csv，roles.csv。
movies.csv包含的是电影的信息，其中每部电影有一个 id（作为检索的 primary key），此外每部电影还拥有 title、year 和 rating 等属性。（数据来自IMDb）。
[movies.csv]
id, name, year, rating
tt0188766,King of Comedy,1999,7.3
tt0286112,Shaolin Soccer,2001,7.3
tt4701660,The Mermaid,2016,6.3
对应的 jsonline 格式如下: 也可以所有字段都是字符串形式，导入的时候会转换成对应的类型
["tt0188766","King of Comedy",1999,7.3]
["tt0286112","Shaolin Soccer",2001,7.3]
["tt4701660","The Mermaid",2016,6.3]["tt0188766","King of Comedy","1999","7.3"]
["tt0286112","Shaolin Soccer","2001","7.3"]
["tt4701660","The Mermaid","2016","6.3"]actors.csv包含的是演员的信息。每个演员也拥有一个 id，以及 name 等属性。
[actors.csv]
id, name
nm015950,Stephen Chow
nm0628806,Man-Tat Ng
nm0156444,Cecilia Cheung
nm2514879,Yuqi Zhang
对应的 jsonline 格式如下:
["nm015950","Stephen Chow"]
["nm0628806","Man-Tat Ng"]
["nm0156444","Cecilia Cheung"]
["nm2514879","Yuqi Zhang"]roles.csv则包含了演员在哪个电影中扮演了哪个角色的信息。其中每一行记录的是指定演员在指定电影里饰演的角色，对应数据库中的一条边。SRC_ID 和 DST_ID 分别是边的源点和目标点，他们分别是actors.csv和movies.csv中定义的primary属性。
[roles.csv]
actor, role, movie
nm015950,Tianchou Yin,tt0188766
nm015950,Steel Leg,tt0286112
nm0628806,,tt0188766
nm0628806,coach,tt0286112
nm0156444,PiaoPiao Liu,tt0188766
nm2514879,Ruolan Li,tt4701660
对应的 jsonline 格式如下:
["nm015950","Tianchou Yin","tt0188766"]
["nm015950","Steel Leg","tt0286112"]
["nm0628806",null,"tt0188766"]
["nm0628806","coach","tt0286112"]
["nm0156444","PiaoPiao Liu","tt0188766"]
["nm2514879","Ruolan Li","tt4701660"]配置文件import.conf，注意每个文件中有两个标题行，因此我们需要指定HEADER=2选项。
{
"schema": [
{
"label": "actor",
"type": "VERTEX",
"properties": [
{ "name": "aid", "type": "STRING" },
{ "name": "name", "type": "STRING" }
],
"primary": "aid"
},
{
"label": "movie",
"type": "VERTEX",
"properties": [
{ "name": "mid", "type": "STRING" },
{ "name": "name", "type": "STRING" },
{ "name": "year", "type": "INT16" },
{ "name": "rate", "type": "FLOAT", "optional": true }
],
"primary": "mid"
},
{
"label": "play_in",
"type": "EDGE",
"properties": [{ "name": "role", "type": "STRING", "optional": true }],
"constraints": [["actor", "movie"]]
}
],
"files": [
{
"path": "actors.csv",
"header": 2,
"format": "CSV",
"label": "actor",
"columns": ["aid", "name"]
},
{
"path": "movies.csv",
"header": 2,
"format": "CSV",
"label": "movie",
"columns": ["mid", "name", "year", "rate"]
},
{
"path": "roles.csv",
"header": 2,
"format": "CSV",
"label": "play_in",
"SRC_ID": "actor",
"DST_ID": "movie",
"columns": ["SRC_ID", "role", "DST_ID"]
}
]
}使用导入配置文件，我们现在可以使用以下命令导入数据：
$ ./lgraph_import
-c import.conf # 从import.conf读取配置信息
--dir /data/lgraph_db # 将数据存放在/data/lgraph_db
--graph mygraph # 导入名为 mygraph 的图注意：
- 如果名为
mygraph的图已存在，导入工具将打印错误消息并退出。要强制覆盖图形，可以使用--overwrite true选项。 - 配置文件和数据文件必须使用 UTF-8 编码（或普通 ASCII 编码，即 UTF-8 的子集）存储。如果任何文件使用 UTF-8 以外的编码（例如，带有 BOM 或 GBK 的 UTF-8）编码，则导入将失败，并输出分析器错误。
在线导入模式可用于将一批文件导入已在运行中的 TuGraph 实例中。这对于处理通常以固定的时间间隔进行的增量批处理更新非常便利。lgraph_import --online true选项使导入工具能够在线模式工作。与离线模式一样，在线模式有自己的命令行选项集，可以使用-h，--help选项进行打印输出：
$ lgraph_import --online true -h
Available command line options:
--online Whether to import online.
-h, --help Print this help message. Default=0.
Available command line options:
--log Log file to use, empty means stderr. Default="".
-v, --verbose Verbose level to use, higher means more verbose.
Default=1.
-c, --config_file Config file path.
-r, --url DB REST API address.
-u, --username DB username.
-p, --password DB password.
-i, --continue_on_error
When we hit a duplicate uid or missing uid, should we
continue or abort. Default=0.
-g, --graph The name of the graph to import into. Default=default.
--skip_packages How many packages should we skip. Default=0.
--delimiter Delimiter used in the CSV files
--breakpoint_continue
When the transmission process is interrupted,whether
to re-transmit from zero package next time. Default=false
-h, --help Print this help message. Default=0.文件的相关配置在配置文件中指定，其格式与离线模式完全相同。但是，我们现在不是将数据导入本地数据库，而是将数据发送到正在运行的 TuGraph 实例中，该实例通常运行在与运行导入工具的客户端计算机不同的计算机上。因此，我们需要指定远程计算机的 HTTP 地址的URL、DB用户和密码。
如果用户和密码有效，并且指定的图存在，导入工具将将数据发送到服务器，服务器随后解析数据并将其写入指定的图。数据将以大约 16MB 大小的包发送，在最近的换行符处中断。每个包都是以原子方式导入的，这意味着如果成功导入包，则成功导入所有数据，否则，任何数据都不会进入数据库。如果指定了--continue_on_error true，则忽略数据完整性错误，并忽略违规行。否则，导入将在第一个错误包处停止，并打印出已导入的包数。在这种情况下，用户可以修改数据以消除错误，然后使用--skip_packages N重做导入以跳过已导入的包。
在线全量导入可用于将一批文件导入运行中的TuGraph实例，TuGraph支持将两种不同类型的数据在线导入到实例中：
- 和离线导入类型相同的原数据文件（csv等）
- TuGraph的底层存储文件，即data.mdb文件，该文件可以由离线导入生成，也可以是其他TuGraph db的文件。 这两种方式的适用场景不同，第一种是直接将数据导入到TuGraph中，优点是一次性自动导入，操作步骤简单。但是会在server端启动一个离线导入线程， 只适合单机情况下的小规模数据导入。第二种是将已经准备好的底层存储文件导入到TuGraph中，虽然需要提前准备好mdb文件，但是对系统资源却没有很高的要求， 而且支持远程下载文件导入，非常方便，适用于高可用模式或者大规模数据的在线导入。
从原数据导入的执行方式是向运行中的TuGraph实例发送导入请求，
实例接到请求后先使用离线导入（V3）的方式将数据导入一个临时的db中，然后在实例中新建子图并将临时db的数据文件迁移到新子图中，最后刷新实例的元数据。
相比在线增量导入，在线全量导入的性能更高。
lgraph_import --online true --online_type 1选项使导入工具能够在线全量导入。
与离线模式一样，在线模式有自己的命令行选项集，可以使用-h，--help选项进行打印输出：
$ lgraph_import --online true --online_type 1 -h
Available command line options:
--online_type The type of import online, 0 for increment, 1 for full
import data,2 for full import file. Default=0.
--v3 Whether to use lgraph import V3. Default=1.
-h, --help Print this help message. Default=0.
Available command line options:
--full Whether to full import online. Default=0.
-h, --help Print this help message. Default=0.
Available command line options:
-c, --config_file Config file path.
-r, --url DB REST API address.
-u, --user DB username.
-p, --password DB password.
-i, --continue_on_error
When we hit a duplicate uid or missing uid, should we
continue or abort. Default=0.
-g, --graph The name of the graph to import into. Default=default.
--delimiter Delimiter used in the CSV files. Default=,.
--log Log dir to use, empty means stderr. Default="".
-v, --verbose Verbose level to use, higher means more verbose.
Default=1.
--overwrite Whether to overwrite the existing DB if it already
exists. Default=0.
--parse_block_size Block size per parse. Default=8388608.
--parse_block_threads
How many threads to parse the data block. Default=5.
--parse_file_threadsHow many threads to parse the files. Default=5.
--generate_sst_threads
How many threads to generate sst files. Default=15.
--read_rocksdb_threads
How many threads to read rocksdb in the final stage.
Default=15.
--vid_num_per_reading
How many vertex data to read each time. Default=10000.
--max_size_per_reading
Maximum size of kvs per reading. Default=33554432.
--compact Whether to compact. Default=0.
--keep_vid_in_memoryWhether to keep vids in memory. Default=1.
--enable_fulltext_index
Whether to enable fulltext index. Default=0.
--fulltext_index_analyzer
fulltext index analyzer. Default=StandardAnalyzer.
Possible values: {<2>: SmartChineseAnalyzer,
StandardAnalyzer}
-h, --help Print this help message. Default=0.文件的相关配置在配置文件中指定，其格式与离线模式完全相同。但是，我们现在不是将数据导入本地数据库，而是将数据导入正在运行的 TuGraph 实例中，
该实例通常运行在与运行导入工具的客户端计算机不同的计算机上。因此，我们需要指定远程计算机的 HTTP 地址的URL、DB用户和密码。
并且，配置文件（config_file参数）要求是 TuGraph 实例机器上的uri路径，其file配置也要求是 TuGraph 实例机器上资源的绝对路径。
如果用户和密码有效，导入工具将在服务器端执行在线全量导入。如果想导入的图已存在，可以使用--overwrite true 选项强制覆盖子图。
从原数据在线全量导入尽管操作简单、性能较高，但是对服务器资源要求较高，且耗时较长。 一种更加通用的方式是先使用离线导入在一个空db中导入子图，得到data.mdb文件，然后把该文件在线导入到 TuGraph服务中。其使用方式如下所示：
$ ./lgraph_import --online true --online_type 2 -h
Available command line options:
--online Whether to import online. Default=0.
--v3 Whether to use lgraph import V3. Default=1.
-h, --help Print this help message. Default=0.
Available command line options:
--online_type The type of import online, 0 for increment, 1 for full
import data,2 for full import file. Default=0.
-h, --help Print this help message. Default=0.
Available command line options:
-r, --url DB REST API address.
-u, --user DB username.
-p, --password DB password.
-g, --graph The name of the graph to import into. Default=default.
--path The path of data file.
--remote Whether to download file from remote server. Default=0.
-h, --help Print this help message. Default=0.除普通在线导入用到的url, user和password参数之外，从数据库文件导入的在线全量导入方式 使用graph参数指定导入的子图名称，path参数指定文件路径，remote指定文件存在在远程或者本地。 如果是本地文件，则需要保证HA集群中所有的节点在path路径下都有该文件。如果是远程文件，则会先下载再导入。 需要注意的是，由于data.mdb只有一份，需要保证HA的各个节点和离线导入生成data.mdb的机器的环境完全一致， 以保证不会出现环境问题。