简介

图数据库是按顶点和边存储数据的非关系型数据库，可用于存储复杂的数据网络模型，如社交网络和事务网络等。

TuGraph 是由北京费马科技有限公司开发的图数据库，本手册介绍了 TuGraph 的功能及使用方法。

TuGraph特性

TuGraph 是支持大数据容量、低延迟查找和快速图分析功能的高效图数据库。同时 TuGraph 也是基于磁盘的数据库，支持存储多达数十 TB 的数据。TuGraph 具有多种 API，使用户能够轻松构建应用程序，同时保持其应用程序的可优化性。

它有如下功能特征：

• 标签属性图模型
• 支持多图
• 完善的ACID事务处理
• 内置 25+ 图分析算法
• 基于web客户端的图可视化工具
• 支持REST API和RPC
• OpenCypher图查询语言
• 基于 C++/Python/Java的存储过程
• 适用于高效图算法开发的Traversal API
• PandaGraph图分析引擎适配器

性能和可扩展性：

• TB级大容量
• 千万顶点/秒的高吞吐率
• 高可用性支持
• 高性能批量导入
• 在线/离线备份

数据模型

图模型

TuGraph是一个具备多图能力的强模式属性图数据库。其支持最多一万亿顶点的有向图构建。

• 多图：在 TuGraph 中，每个数据库服务器可以承载多个图模型，每个图模型可以有自己的访问控制配置，数据库管理员可以创建或删除指定图模型。
• 属性图：TuGraph 中的顶点和边可以具有与其关联的属性，每个属性可以有不同的类型。
• 强模式：每个顶点和边必须有一个标签，且创建标签后，无法更改属性数量及类型。
• 有向边：TuGraph 中的边为有向边，若要模拟无向边，用户可以创建两个方向相反的边。

数据类型

TuGraph 支持多种可用作属性的数据类型，具体支持的数据类型如下所示：

表 1. TuGraph 所支持的数据类型

BIN类型的数据在输入输出时使用BASE64编码

索引

TuGraph 支持对顶点字段进行索引。

索引可以是唯一索引或非唯一索引。如果为顶点标签创建了唯一索引，则 TuGraph 将在修改该标签的顶点时会先执行数据完整性检查，以确保该索引的唯一性。

每个索引都基于一个标签的一个字段构建，可以使用同一标签对多个字段进行索引。

BIN类型的字段不能建立索引。

软件授权

TuGraph使用指定授权文件进行授权。授权文件规定了TuGraph的期限及配置，包括使用CPU核心数量以及是否可启用集群容灾模式等，如果您需要试用或购买新的授权，请与我们联系：market@fma.ai。

安装

系统要求

表2 是TuGraph对系统的配置要求。目前我们建议用户使用NVMe SSD配合较大的内存配置以获取最佳性能。

表2. TuGraph系统要求

通过docker镜像安装

安装TuGraph最简单的方法是通过docker镜像来安装和运行TuGraph。同一个docker镜像可以在不同的Linux发行版本上运行而不需要再额外安装软件包，因此我们推荐用户使用这种方式进行安装。

想要使用docker镜像进行安装，用户首先需要确保自己的服务器中已经安装了docker。以下命令可以判断docker是否已经安装：

$ sudo docker --version

如果该命令能顺利打印出docker版本号，则证明docker已经正常安装，否则需要先安装docker。安装docker的过程可参考其官网 https://docs.docker.com/install/ 。

目前，TuGraph提供基于ubuntu 16.04 LTS和Centos 7.3系统的镜像文件。用户可以通过费马科技的官网下载镜像文件或者联系我们以获取镜像：market@fma.ai。

镜像文件是一个名为lgraph_x.y.z.tar的压缩文件，其中x.y.z是TuGraph的版本号。该压缩包可通过以下命令加载到docker镜像中：

$ sudo docker import tugraph_x.y.z.tar

如果加载成功，您的计算机上应具有名为 tugraph_x.y.z 的 docker 镜像，您可以使用以下命令运行该镜像：

$ sudo docker run -v /data_dir_on_host:/data_dir_in_docker -it tugraph_x.y.z /bin/bash

Ubuntu下的安装方法

除了通过docker镜像安装外，我们也提供了用于在Ubuntu上安装的TuGraph的.deb安装包，其中包含了TuGraph可执行文件以及编写嵌入式程序和存储过程所需的头文件和相关库文件。

使用已经下载完成的tugraph_x.y.z.deb安装包在终端下安装，只需要运行以下命令：

$ sudo dpkg -i tugraph_x.y.z.deb

该命令默认将TuGraph安装于/usr/local目录下。用户也可以通过指定 --instdir=<directory> 选项更改安装目录。

CentOS下的安装方法

TuGraph提供.rpm安装包，包内所含功能模块与.deb包一致。在CentOS系统下安装、卸载及使用过程也与Ubuntu系统下相似。 在终端下安装只需运行以下命令：

$ rpm -ivh tugraph-x.y.z.rpm

如果需要安装到指定目录，可以通过--prefix选项指定安装目录。

数据导入

在安装成功后，您可以使用lgraph_import批量导入工具将现有数据导入 TuGraph。

lgraph_import支持从 CSV 文件和 SQL 数据源导入数据。它有两种模式：

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

离线全量导入

离线模式只能在离线状态的服务器使用。离线导入会创建一张新图，因此更适合新安装的 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="".
$ ./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_file: 日志文件路径。默认为空字符串，此时将日志信息输出到控制台。
• --verbose 0/1/2: 日志等级，等级越高输出信息越详细。默认为1。
• -i, --continue_on_error true/false: 在碰到错误时跳过错误并继续，默认为false，碰到错误立即退出。
• -d, --dir {diretory}: 数据库目录，导入工具会将数据写到这个目录。默认为./db。
• -u, --username {user}: 数据库用户名。需要是管理员用户才能执行离线导入。
• -p, --password {password}: 指定的数据库用户的密码
• --overwrite true/false: 是否覆盖数据。设为true时，如果数据目录已经存在，则覆盖数据。默认为false。
• -g, --graph {graph_name}: 指定需要导入的图种类。
• -h, --help: 输出帮助信息。

配置文件

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

下面是一个示例配置文件：

# 注释行以井号开头
# 注释可以有任意多行
[actors.csv]                  # 文件路径
LABEL=actor, HEADER=2         # 顶点标签和文件头的行数
aid:STRING:ID, name:STRING    # 每一行的名称与数据类型
[movies.csv]
LABEL=movie
mid:STRING:ID,name:STRING,year:INT16,rate:FLOAT:OPTIONAL,tagline:STRING:OPTIONAL
[roles.csv]
LABEL=play_in,SRC_ID=actor:aid,DST_ID=movie:mid  # 边标签，源顶点与目标顶点id
SRC_ID, role:STRING, DST_ID

此示例文件描述三个 CSV 文件：两个顶点文件（actors.csv 和movies.csv）和一个边文件（roles.csv）。同时配置文件还指定了每个文件的格式。

配置文件由一组或多组文件描述组成，由可选的空行和注释行分隔。每组文件描述对要导入的数据文件进行说明，它包含三个部分，每个部分位于单独的行中：

1. 第一部分是文件路径，用半括号[和]括起来，
2. 第二部分是目标描述，
3. 第三部分是列映射。

目标描述

该部分包含指定标签的顶点或边的列表。目标描述部分的规则：对于顶点，它指定顶点标签;对于边，它指定边标签以及边的源顶点和目标顶点 id。

顶点数据文件的目标描述具有以下格式：

LABEL={顶点label}, HEADER={文件头行数}

其中LABEL指定该类顶点的label，HEADER指定的是该文件中包含了多少行的文件头。CSV文件往往使用一至两行来描述该文件中每一列的含义，此时可以通过HEADER来指示import工具跳过这些文件头。HEADER可以省略，默认为0。

边文件的数据说明格式如下：

LABEL={边label}, SRC_ID={src_label}:{src_field}, DST_ID={dst_label}:{dst_field}, HEADER={文件头行数}

其中LABEL指定该类边的label，{src_label}:{src_id_field}是边的源顶点的标签和 id 字段。例如，SRC_ID=actor:aid表示边的源顶点具有标签actor，并且可以使用aid字段进行唯一标识。

同样，{dst_label}:{dst_id_field}表示边的目标顶点的标签和 id 字段。

列映射

列映射将数据文件中的每一列映射到相应的属性。它涉及多个由逗号分隔的列说明：

列说明 :=
    | SRC_ID
    | DST_ID
    | SKIP
    | {field_name}:{DataType}[:ID|OPTIONAL]

其中：

• SRC_ID表示包含源顶点 id 的列，该列仅对边数据文件有效，
• DST_ID表示包含目标顶点 id 的列，
• SKIP使导入工具跳过此列，

和：

• field_name是结果顶点/边中的相应字段（属性）的名称，
• DataType指定该字段的数据类型，可以是BOOL，INT8，INT16，INT32，INT64，DATE，DATETIME，FLOAT，DOUBLE，STRING和BIN，
• ID表示顶点标签的唯一标识符 id 字段，
• OPTIONAL表示此字段是可选的。

列映射示例如下：

aid:INT64:ID, age:FLOAT:OPTIONAL, SKIP, SKIP, name:STRING # 有效
SRC_ID, DST_ID, weight:FLOAT # 有效
aid:ID # 无效：缺少数据类型
aid:STRING:SRC_ID:ID  # 无效：无法同时指定 SRC_ID 和 ID
f:INT:ID:OPTIONAL # 无效：无法同时指定 ID 和 OPTIONAL
f:INT:FLOAT # 无效：无法同时指定两种数据类型

离线导入示例

在这个例子中，我们使用上面描述的电影-演员数据来演示导入工具的使用方法。待导入数据分为三个文件：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

actors.csv包含的是演员的信息。每个演员也拥有一个id，以及name等属性。

[actors.csv]
  id, name
  nm015950,Stephen Chow
  nm0628806,Man-Tat Ng
  nm0156444,Cecilia Cheung
  nm2514879,Yuqi Zhang

roles.csv则包含了演员在哪个电影中扮演了哪个角色的信息。其中每一行记录的是指定演员在指定电影里饰演的角色，对应数据库中的一条边。SRC_ID 和 DST_ID 分别是边的源顶点和目标顶点，他们分别是actors.csv和movies.csv中定义为 ID 的域。

[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

现在我们来建立一个配置文件，来告诉lgraph_import工具如何导入这些文件：

# import.conf
[actors.csv]
LABEL=actor, HEADER=2
aid:STRING:ID, name:STRING
[movies.csv]
LABEL=movie, HEADER=2
mid:STRING:ID,name:STRING,year:INT16,rate:FLOAT:OPTIONAL,tagline:STRING:OPTIONAL
[roles.csv]
LABEL=play_in,SRC_ID=actor:aid,DST_ID=movie:mid, HEADER=2
SRC_ID, role:STRING, DST_ID

注意每个文件中有两个标题行，因此我们需要指定HEADER=2选项。使用导入配置文件，我们现在可以使用以下命令导入数据：

$ ./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.
    -h, --help          Print this help message. Default=0.

文件的相关配置在配置文件中指定，其格式与离线模式完全相同。但是，我们现在不是将数据导入本地数据库，而是将数据发送到正在运行的 TuGraph 实例中，该实例通常运行在与运行导入工具的客户端计算机不同的计算机上。因此，我们需要指定远程计算机的 HTTP 地址的URL、DB用户和密码。

如果用户和密码有效，并且指定的图存在，导入工具将将数据发送到服务器，服务器随后解析数据并将其写入指定的图。数据将以大约 16MB 大小的包发送，在最近的换行符处中断。每个包都是以原子方式导入的，这意味着如果成功导入包，则成功导入所有数据，否则，任何数据都不会进入数据库。如果指定了--continue_on_error true，则忽略数据完整性错误，并忽略违规行。否则，导入将在第一个错误包处停止，并打印出已导入的包数。在这种情况下，用户可以修改数据以消除错误，然后使用--skip_packages N重做导入以跳过已导入的包。

服务器配置

配置参数

TuGraph 服务器在启动时从配置文件和命令行选项加载配置，如果在配置文件和命令行中同一选项指定了不同的值，将优先使用命令行中指定的值。

具体参数及其类型描述如下：

服务器配置文件

TuGraph 的配置文件以 JSON 格式存储。建议将大多数配置存储在配置文件中，并且仅在需要时使用命令行选项临时修改某些配置参数。

一个典型的配置文件如下：

{
    "directory" : "/var/lib/lgraph/data",
    "license" : "/var/lib/lgraph/fma.lic",
    "port" : 7090,
    "rpc_port" : 9090,
    "enable_ha" : false,
    "verbose" : 1,
    "log_file" : "/var/log/lgraph.log",
    "ssl_auth" : false,
    "server_key" : "/usr/local/etc/lgraph/server-key.pem",
    "server_cert" : "/usr/local/etc/lgraph/server-cert.pem",
}

命令行参数

lgraph_server命令用于启动 TuGraph 服务器实例。 命令行选项可用于在启动 TuGraph 服务器时覆盖从配置文件加载的配置。

除了 配置参数中描述的所有配置选项外，lgraph_server也会确定已启动服务器的运行模式，运行模式可以为standard或daemon，有关运行模式的具体细节可参阅 运行模式。

一个典型的lgraph_server命令如下：

$ lgraph_server --config ./local_lgraph.json --port 7777 --mode start

服务启停

运行模式

TuGraph可以作为前台普通进程启动，也可以作为后台守护进程启动。

当作为普通进程运行时，TuGraph 可以直接将日志打印到终端，这在调试服务器配置时非常方便。但是，由于前台进程在终端退出后被终止，因此用户须确保在 TuGraph 服务器处于运行状态时，终端保持打开状态。

另一方面，在守护进程模式下，即使启动它的终端退出，TuGraph 服务器也可以继续运行。因此，在长时间运行的服务器下推荐以守护进程模式启动 TuGraph 服务器。

运行普通进程

lgraph_server -d run命令可以将TuGraph作为普通进程运行。普通进程依赖命令行终端，因此终端结束时，TuGraph进程也会自动终止。普通进程模式配合--log_file ""可以将进程日志直接输出到终端，因此更方便调试。

普通模式的运行输出示例如下所示：

$ ./lgraph_server -c lgraph_standalone.json --log_file ""
20200508120723.039: **********************************************************************
20200508120723.039: *               LightningGraph Graph Database v1.10.0                *
20200508120723.040: *                                                                    *
20200508120723.041: *      Copyright(C) 2018 FMA Technology. All rights reserved.        *
20200508120723.041: *                                                                    *
20200508120723.044: *             Licensed host: hostname      threads:0, ha:0           *
20200508120723.044: **********************************************************************
20200508120723.044: Server is configured with the following parameters:
20200508120723.045:   data directory:    ./lgraph_db
20200508120723.045:   license:           ./fma.lic
20200508120723.046:   enable ha:          0
20200508120723.046:   async:              0
20200508120723.047:   host:               127.0.0.1
20200508120723.047:   REST port:          7071
20200508120723.048:   RPC port:           9091
20200508120723.048:   enable rpc:         0
20200508120723.051:   optimistic txn:     0
20200508120723.059:   verbose:            1
20200508120723.074:   log_file:
20200508120723.074:   ssl_auth:           0
20200508120723.075:   resource dir:       ./resource
20200508120723.077: Loading DB state from disk
20200508120723.110: [RestServer] Listening for REST on port 7071
20200508120723.110: [LGraphService] Server started.

普通进程模式下，用户可以通过按 CTRL+C 来提前终止TuGraph进程。

启动服务

TuGraph需要通过 lgraph_server -d start 命令行启动，启动命令示例如下：

$ ./lgraph_server -d start -c lgraph_daemon.json
Starting lgraph...
The service process is started at pid 12109.

此命令启动的 TuGraph 服务器进程为守护进程，它将从文件lgraph_daemon.json加载相关配置。

服务器启动后，它将开始在日志文件中打印日志，之后可用该日志文件确定服务器的状态。

停止服务

用户可以使用kill命令以及lgraph_server -d stop命令停止 TuGraph 守护进程。

由于可能在同一台计算机上运行多个 TuGraph 服务器进程，因此我们使用.pid文件区分不同的服务器进程，该文件写入启动该进程的工作目录。因此，需要在相同工作目录中运行lgraph_server-d stop命令，以停止正确的服务器进程。

user@host:~/tugraph$ ./lgraph_server -d start -c lgraph_standalone.json
20200508122306.378: Starting lgraph...
20200508122306.379: The service process is started at pid 93.
user@host:~/tugraph$ cat ./lgraph.pid
93
user@host:~/tugraph$ ./lgraph_server -d stop -c lgraph_standalone.json
20200508122334.857: Stopping lgraph...
20200508122334.857: Process stopped.

重启服务

用户也可以通过lgraph_server -d restart来重启TuGraph服务：

$ ./lgraph_server -d restart
Stopping lgraph...
Process stopped.
Starting lgraph...
The service process is started at pid 20899.

使用API访问数据库

在 TuGraph 数据库中访问数据也有多种方法：

• REST API: TuGraph 提供了一组涵盖数据库的基本操作的 REST API，包括调用 Cypher 查询和调用插件。REST API 的完整文档请参阅 TuGraph REST API Manual。
• OpenCypher 查询语言: TuGraph 支持开源图数据库查询语言 OpenCypher。除了 OpenCypher 的标准语法之外，TuGraph 还有自己的扩展。有关如何在 TuGraph 中使用扩展 OpenCypher 的详细信息，请参阅 TuGraph OpenCypher Manual。
• 插件 API: 除了 OpenCypher 查询之外，TuGraph 还提供对用户公开低优先级操作的插件 API。用户可以使用插件 API 编写插件并将其加载到服务器中。由于插件是使用命令性语言编写的（目前我们支持C++、Java和Python），因此它们可用于实现任意复杂的逻辑。如果考虑到性能问题，插件可以用原生语言编写以方便优化到最佳。插件 API 以及如何管理插件的参考请参阅 TuGraph Plugin Manual。

用户可以通过以下方式访问 TuGraph 服务器：

• lgraph_cypher 命令行查询客户端: 在服务器上执行 OpenCypher 查询并在终端中打印结果的命令行工具。
• TuGraph 可视化工具: 可用于发送 Cypher 查询和可视化生成的子图的 Web 界面，它也可以用来管理和调用插件。
• HTTP 请求: TuGraph 直接使用 HTTP 提供 REST 请求，用户可以使用 HTTP 客户端将 REST 请求发送到 TuGraph 服务器。
• TuGraph 客户端 SDK: TuGraph 以多种语言（当前C++、Java 和 Python）提供客户端 SDK，以供用户应用程序调用。

lgraph_cypher和 TuGraph 可视化工具提供交互式界面，因此更适合人工使用，而 REST API 和 SDK 则设计为程序使用。

lgraph_cypher 使用说明

TuGraph 发布版本附带名为lgraph_cypher的查询客户端，可用于向 TuGraph 服务器提交 OpenCypher 请求。lgraph_cypher客户端有两种执行模式：单命令模式和交互式模式。

单命令模式

在单命令模式下，lgraph_cypher可用于提交单个 Cypher 查询并将结果直接打印到终端，打印结果也可以容易地重定向写入指定文件。当用户需要从服务器获取大量结果并将其保存在文件中时，这非常便利。

在此模式下，lgraph_cypher工具具有以下选项：

命令行参数:

命令示例:

cypher命令文件查询：

$ ./lgraph_cypher.py -c /home/usr/lgraph_standalone.json -u user -P password -f /home/usr/cypher.json

cypher命令单句查询：

$ ./lgraph_cypher.py -c /home/usr/lgraph_standalone.json -u user -P password -s "MATCH (n) RETURN n"

交互模式

lgraph_cypher也可以在交互模式下运行。在交互式模式下，客户端与服务器保持连接，并在读取-评估-打印-循环中与用户进行交互。

进入lgraph_cypher交互模式:

如不加-f或-s命令行选项，运行lgraph_cypher时将会进入交互模式。使用方式如下：

$ ./lgraph_cypher.py -c /home/usr/lgraph_standalone.json -u admin -P admin123456

如成功进入则会显示相应登录成功信息：

**********************************************************************
*               LightningGraph Graph Database X.Y.Z                  *
*                                                                    *
*      Copyright(C) 2018 FMA Technology. All rights reserved.        *
*                                                                    *
**********************************************************************
login success
----------------------------------
Host: 127.0.0.1
Port: 7071
Username: admin
----------------------------------
type ":help" to see all commands.
>

现在我们也提供一个交互式 shell ，用于用户输入 Cypher 查询语句或使用:help命令来检查可用命令。

command种类与说明:

除 Cypher 查询外，lgraph_cypher 的 shell 还接受以下命令：

注意:

• 每条命令都应该以冒号开始 :.

:save 命令例子:

:save all -f /home/usr/saved.txt match (n) where return n, n.name limit 1000

cypher查询命令:

在交互模式下，用户也可直接输入单句cypher命令进行查询，以";"结束。输入命令不区分大小写。例子如下：

login success
>MATCH (n) RETURN n, n.name;
+---+---+-------------+
|   | n |n.name       |
+---+---+-------------+
| 0 | 0 |david        |
| 1 | 1 |Ann          |
| 2 | 2 |first movie  |
| 3 | 3 |Andres       |
+---+---+-------------+
time spent: 0.000520706176758
size of query: 4
>

lgraph_cypher输入命令时支持多行输入，用户可使用ENTER键将长查询语句分多行输入。多行输入情况下命令行开头会从>变为=>，然后用户可以继续输入查询的其余部分。

例子如下：

login success
>MATCH (n)
=>WHERE n.uid='M11'
=>RETURN n, n.name;

辅助功能:

历史查询： 在交互模式下按上下方向键可查询输入历史。

自动补全： lgraph_cypher会根据输入历史进行自动补全。在补全提示出现的情况下，按下右方向键就会自动补全命令。

可视化工具

TuGraph 提供基于 Web 的可视化界面，使用户能够：

• 执行 Cypher 查询并对生成的子图进行可视化
• 管理数据库中的图
• 管理和调用插件
• 实时检查数据库状态
• 管理用户帐户和对单个图的访问权限
• 管理数据库中当前运行的任务
• 分析审计日志

有关 TuGraph 可视化工具的更详细说明，请参阅 TuGraph Visualizer Manual。

高可用模式

原理

TuGraph通过多机热备份来提供高可用模式（HA模式）。在高可用模式下，对数据库的写操作会被同步到所有服务器上，这样即使有部分服务器宕机也不会影响服务的可用性。

在高可用模式下，多个 TuGraph 服务器组成一个备份组。每个备份组由三个或更多 TuGraph 服务器组成，其中某台服务器会作为leader，而其他复制组服务器则作为follower。写入请求由leader提供服务，该leader将每个请求复制同步到follower，并在请求同步到服务器后才能响应客户端。这样，如果任何服务器发生故障，其他服务器仍将具有到目前为止已写入的所有数据。如果leader服务器发生故障，其他服务器将自动选择出新的leader。

准备工作

要启用高可用模式，用户需要：

• 三台及以上的 TuGraph 服务器实例。

• 获得一个具有高可用的 license 文件，具体请洽我们的经销商。
• 在启动 lgraph_server 时打开高可用模式，可以使用配置文件或者命令行将enable_ha选项设置为true。
• 设置正确的rpc_port，可通过配置文件或者命令行设置。

启动第一台服务器

第一台服务器在启动之后会将自己选举为leader，并组织一个只有自己的备份组。

第一台服务器需使用--master ""或--master BOOTSTRAP选项启动，具体取决于第一台服务器中是否已经具有数据。

• --master "": 如果第一台服务器中没有数据，用户可以直接使用--master ""选项启动服务器。
• --master BOOTSTRAP: 如果第一台服务器中已有数据（以lgraph_import工具导入或从非高可用模式的服务器传输得到），并且之前并未在高可用模式下使用，则用户应使用BOOTSTRAP选项在引导模式下启动服务器。在引导模式下，服务器在将新加入的服务器添加到备份组之前会将自己的数据复制到新服务器中，以使每个服务器中的数据保持一致。

启动第一台已经有数据的服务器的命令行示例如下：

$ ./lgraph_server -c lgraph.json --rpc_port 9090 --enable_ha true --master BOOTSTRAP

启动后续服务器

启动第一台服务器后，它将形成一个服务器备份组。但这是一个易受攻击的状态：如果服务器崩溃，服务将中断。在 TuGraph 中，在保证服务可用性的前提下，备份组最多可以承受 （N-1）/2 数量的服务器崩溃。因此，在一个备份组中必须至少有三台服务器，以在一个服务器丢失时保证服务可用性。

要将新服务器添加到备份组，应使用--master {HOST：PORT}选项，其中HOST可以是该备份组中已有的任何服务器的 IP 地址，而PORT是其 RPC 端口。例如：

./lgraph_server -c lgraph.json --rpc_port 9091 --enable_ha true --master 192.168.1.120:9090

此命令将启动一台高可用模式的 TuGraph 服务器，并尝试将其添加到包含服务器192.168.1.120：9090的备份组中。请注意，加入备份组需要服务器将其数据与备份组的leader服务器同步，此过程可能需要相当长的时间，具体取决于数据的大小。

停止服务器

当服务器通过CTRL-C下线时，它将通知当前的leader服务器，告知其从备份组中删除该下线的服务器。如果leader服务器下线，它将在下线前将leader身份权限传给另一台服务器。

如果服务器被终止或者与备份组中的其他服务器失去连接，则该服务器将被视为失败节点，leader服务器将在特定时限后将其从备份组中删除。

如果任何服务器离开备份组并希望重新加入，则必须从--master {HOST：PORT}选项开始，其中HOST是当前备份组中的某台服务器的 IP 地址。

重启服务器

不建议重新启动整个备份组，因为它会中断服务。如果需要，可以关闭所有服务器。但在重新启动时，必须首先启动最后一个关闭的服务器。

查看服务器状态

备份组的当前状态可以在 TuGraph 可视化工具、REST API 以及 Cypher 查询中获取。

在 TuGraph 可视化工具中，可以在 DBInfo 部分中找到备份组中的服务器及其角色列表。

使用 REST API时，可以使用GET /info/peers 请求获取信息。

在 Cypher 中，使用CALL dbms.listServers()语句来查询当前备份组的状态信息。

高可用模式下数据同步问题

在高可用模式下，同一备份组中的不同服务器可能并不总是处于相同的状态。出于性能原因，如果请求已同步到超过一半的服务器，则leader服务器将认为该请求属于committed状态。尽管其余服务器最终将收到新请求，但服务器的状态不一致将持续一段时间。客户端也可能向刚刚重新启动的服务器发送请求，从而具有较旧的状态，并且正在等待加入备份组。

为了确保客户端看到一致连续的数据，特别是为了摆脱反向时间旅行问题（其中客户端读取比以前看到的状态更旧的状态），每个 TuGraph 服务器都会保持一个单调增加的数据版本号。备份组中数据版本号到数据库状态的映射全局一致，这意味着如果两台服务器具有相同的数据版本号，则它们必须具有相同的数据。响应请求时，服务器在响应中包含了其数据版本号。因此，客户端可以知道它看到了哪个版本。客户端可以选择发送此数据版本号以及请求。收到具有数据版本号的请求后，服务器会将数据版本号与其当前版本进行比较，如果其自己的版本低于请求的版本，服务器将拒绝该请求。此机制可确保客户端永远不会读取比以前较旧的状态。

数据库管理

日志信息

TuGraph 保留两种类型的日志：服务器日志和审计日志。服务器日志记录人为可读的服务器状态信息，而审核日志维护服务器上执行的每个操作加密后的信息。

服务器日志

服务器日志会跟踪服务器的状态信息（如服务器启动和停止等）以及服务器已提供的请求及其相应的响应。服务器日志的详细程度可通过verbose选项进行配置。日志的位置在log_file选项中指定。

默认的verbose等级为1，此等级下，服务器将仅打印主要事件的日志，如服务器启动/停止。请求和响应不会记录在此级别。

审计日志

审核日志记录每个请求和响应，以及发送请求的用户以及收到请求的时间。审核日志只能是打开或关闭状态。可以使用 TuGraph 可视化工具和 REST API 查询结果。

数据导出

TuGraph可以通过 lgraph_export 工具来对已经导入成功的数据库进行数据导出。 lgraph_export 工具可以将指定TuGraph数据库的数据以 csv 文件形式导出到指定目录，同时导出这些数据进行再导入时需要的配置文件 import.config ，详细描述可参见配置文件。

该工具的命令示例如下：

$ lgraph_export -d {database_dir} -e {export_destination_dir} -g {graph_to_use} -u {username} -p {password}

其中：

• -d {database_dir} 指定需要进行数据导出的数据库所在目录，默认值为 ./testdb。
• -e {export_destination_dir} 指定导出文件存放的目录，默认值为 ./exportdir。
• -g {graph_to_use} 指定图数据库的种类，默认为 default 。
• -u {username} 指定进行该导出操作的用户的用户名。
• -p {password} 指定进行该导出操作的用户的用户密码。
• -h 除上述指定参数外，也可以使用该参数查看该工具的使用帮助。

数据备份

TuGraph可以通过 lgraph_backup 工具来进行数据备份。 lgraph_backup 工具可以将一个TuGraph数据库中的数据备份到另一个目录下，它的用法如下：

$ lgraph_backup -s {source_dir} -d {destination_dir} -c {true/false}

其中：

• -s {source_dir} 指定需要备份的数据库（源数据库）所在目录。
• -d {destination_dir} 指定备份文件（目标数据库）所在目录。 如果目标数据库不为空，lgraph_backup 会提示是否覆盖该数据库。
• -c {true/false} 指明是否在备份过程中进行compaction。 compaction能使产生的备份文件更紧凑，但备份时间也会变长。该选项默认为 true。

数据预热

TuGraph 是基于磁盘的数据库，仅当访问数据时，数据才会加载到内存中。因此在服务器刚开启后的一段时间内，系统性能可能会由于频繁的IO操作而变差。此时我们可以通过事先进行数据预热来改善这一问题。

数据预热可以通过工具 lgraph_warmup 来进行。它的使用示例如下：

$ lgraph_warmup -d {directory} -g {graph_list}

其中：

• -d {db_dir} 选项指定了 TuGraph 服务器的数据目录

• -g {graph_list} 选项指定需要进行数据预热的图名称，用逗号分隔

根据数据大小和所使用的磁盘类型不同，预热过程运行时间也不同。机械磁盘上预热一个大数据库可能耗时较长，请耐心等待。

任务管理

TuGraph 会跟踪长时间运行的任务。可以使用 REST API 、Cypher 以及 TuGraph 可视化工具查询当前正在运行的任务列表。长时间运行的任务可以由数据库管理员终止。

常见问题

1. "Error opening config file xxx, exiting..."

这一错误出现在启动TuGraph服务时，原因是程序无法正确读取该配置文件。请确认该配置文件路径正确，并且具有读取权限。

2. "Failed to parse command line option: Option xxx cannot be recognized."

这一错误出现在使用TuGraph的命令行时，原因是该命令行参数无法正确识别，一般是因为参数名错误。可以使用-h, --help来打印符合要求的选项。

3. "Error opening license file xxx"

这一错误意味着许可证文件的路径设置不正确，或者用户无法访问该文件。