数据导入

此文档主要介绍 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 类型的）

  • primary (仅点配置，必选，主键字段，需指定一个 property，用来唯一确定一个点)

  • 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.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重做导入以跳过已导入的包。