数据导入

此文档主要介绍 TuGraph 的数据导入功能。其中包括 CSV 格式的分隔符，jsonline 的格式示例，以及导入在线和离线的两种模式。

1.简介

在图数据库服务安装成功后，您可以使用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 支持两种导入模式：

• 离线模式：读取数据并将其导入指定服务器的数据文件，应仅在服务器离线时完成。
• 在线模式：读取数据并将其发送到工作中的服务器，然后将数据导入其数据库。

2.CSV文件格式分隔符

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"

3.配置文件

lgraph_import工具通过指定的配置文件进行环境配置。配置文件描述输入文件的路径、它们所代表的点/边以及点/边的格式。

3.1.配置文件格式

配置文件包含两部分：schema 和 files。schema部分定义 label，files部分描述要导入的数据文件。

3.1.1.关键字

• 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 (仅边配置，值是目的点标签)

3.1.2.索引长度

因为TuGraph对key的长度有限制，唯一索引不允许建立超过限制长度的索引，而非唯一索引会对超过长度限制的属性进行截断处理，并且在通过迭代器遍历非唯一索引时，拿到的key也是经过截断的，可能和预期不一致。针对不同类型的非唯一索引，截断长度是不同的。

3.1.2.1.unique索引

unique索引是全局唯一的，该索引key的最大长度是480bytes。primary作为特殊的unique索引，因此最大key的长度也是480bytes，超过无法建立索引。

3.1.2.2.pair_unique索引

pair_unique索引是指两点间唯一的索引，这种类型的索引只能创建于边的schema中，这种索引在用户指定的key后面加上了源点和目标点的vid，每个vid是5bytes长度。因此最大key的长度是470bytes，超过无法建立索引。

3.1.2.3.非唯一索引

非唯一索引是指既没有设置unique为1，也没有设置pair_unique为1的索引，在TuGraph的实现中，此类索引一个key可能映射到多个值，为了加速查找和写入，在用户指定的key后面加上了一组vid或euid中的最大值。其中对于创建于点中的非唯一索引，key后面跟着vid，每个vid是5bytes长度，因此最大长度是475bytes。 对于创建于边中的非唯一索引，key后面跟着euid，每个euid是24bytes长度，因此最大长度是456bytes。索引key超过对应长度则会自动截断。

3.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",
      "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，然后再执行三个文件的数据导入。

4.离线全量导入

离线模式只能在离线状态的服务器使用。离线导入会创建一张新图，因此更适合新安装的 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: 输出帮助信息。

4.1.离线导入示例

在这个例子中，我们使用上面描述的电影-演员数据来演示导入工具的使用方法。待导入数据分为三个文件：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）编码，则导入将失败，并输出分析器错误。

5.在线增量导入

在线导入模式可用于将一批文件导入已在运行中的 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重做导入以跳过已导入的包。

6.在线全量导入

在线全量导入可用于将一批文件导入运行中的TuGraph实例，TuGraph支持将两种不同类型的数据在线导入到实例中：

1. 和离线导入类型相同的原数据文件（csv等）
2. TuGraph的底层存储文件，即data.mdb文件，该文件可以由离线导入生成，也可以是其他TuGraph db的文件。 这两种方式的适用场景不同，第一种是直接将数据导入到TuGraph中，优点是一次性自动导入，操作步骤简单。但是会在server端启动一个离线导入线程， 只适合单机情况下的小规模数据导入。第二种是将已经准备好的底层存储文件导入到TuGraph中，虽然需要提前准备好mdb文件，但是对系统资源却没有很高的要求， 而且支持远程下载文件导入，非常方便，适用于高可用模式或者大规模数据的在线导入。

6.1 从原数据导入

从原数据导入的执行方式是向运行中的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 选项强制覆盖子图。

6.2 从数据库文件导入

从原数据在线全量导入尽管操作简单、性能较高，但是对服务器资源要求较高，且耗时较长。 一种更加通用的方式是先使用离线导入在一个空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的机器的环境完全一致， 以保证不会出现环境问题。