快速入门

本手册将逐步指导您使用 Nebula Graph,包括:

  • 安装
  • 数据建模
  • 增删改查
  • 批量插入
  • 数据导入工具

安装

我们推荐使用 docker compose 来安装 Nebula Graph, 具体步骤可以参考我们录制的操作视频

除了使用 Docker,您还可以选择编译源码或者rpm/deb 包 方式安装 Nebula Graph

如果您在安装过程中遇到任何问题,可以前往 Nebula Graph 官方论坛 提问,我们有专门的值班开发人员为您解答问题。

数据建模

在本手册中,我们将通过下图所示的数据集向您展示如何使用 Nebula Graph 数据库。

image

上图中有两个标签(playerteam)以及两条边类型(servefollow)。

创建并使用图空间

Nebula Graph 中的图空间类似于传统数据库中创建的独立数据库,例如在 MySQL 中创建的数据库。 首先,您需要创建一个图空间并使用 (use) 它,然后才能执行其他操作。

您可以通过以下步骤创建并使用图空间:

  1. 检查集群机器状态:

    nebula> SHOW HOSTS;
    ================================================================================================
    | Ip            | Port  | Status | Leader count | Leader distribution | Partition distribution |
    ================================================================================================
    | 192.168.8.210 | 44500 | online |              |                     |                        |
    ------------------------------------------------------------------------------------------------
    | 192.168.8.211 | 44500 | online |              |                     |                        |
    ------------------------------------------------------------------------------------------------
    

    状态 online 表示存储服务进程 storaged 已经成功连接上元数据服务进程 metad

  2. 输入以下语句创建图空间:

    nebula> CREATE SPACE nba (partition_num=10, replica_factor=1);
    

    这里:

    • partition_num:指定一个副本中的分区数。通常为全集群硬盘数量的 5 倍。
    • replica_factor:指定集群中副本的数量,通常生产环境为 3,测试环境可以为 1。由于采用多数表决原理,因此需为奇数。

      你可以通过 SHOW HOSTS 命令检查机器和 partition 分布情况:

      nebula> SHOW HOSTS;
      ================================================================================================
      | Ip            | Port  | Status | Leader count | Leader distribution | Partition distribution |
      ================================================================================================
      | 192.168.8.210 | 44500 | online | 8            | nba: 8              | test: 8                |
      ------------------------------------------------------------------------------------------------
      | 192.168.8.211 | 44500 | online | 2            | nba: 2              | test: 2                |
      ------------------------------------------------------------------------------------------------
      

      若发现机器都已在线 (online),但 Leader distribution 分布不均(如上),则可以通过命令 (BALANCE LEADER) 来触发 partition 重分布:

      nebula> BALANCE LEADER;
      ================================================================================================
      | Ip            | Port  | Status | Leader count | Leader distribution | Partition distribution |
      ================================================================================================
      | 192.168.8.210 | 44500 | online | 5            | nba: 5              | test: 5                |
      ------------------------------------------------------------------------------------------------
      | 192.168.8.211 | 44500 | online | 5            | nba: 5              | test: 5                |
      ------------------------------------------------------------------------------------------------
      

      具体解释可以见这里

  3. 输入以下语句来指定使用的图空间:

    nebula> USE nba;
    
  4. 现在,您可以通过以下语句查看刚创建的空间:

    nebula> SHOW SPACES;
    

    返回以下信息:

    ========
    | Name |
    ========
    | nba  |
    --------
    

定义数据的 Schema

Nebula Graph 中,我们将具有相同属性的点分为一组,该组即为一个标签。CREATE TAG 语句定义了一个标签,标签名称后面的括号中是标签的属性和属性类型。CREATE EDGE 语句定义边类型,类型名称后面的括号中是边的属性和属性类型。

您可以通过以下步骤创建标签和边类型:

  1. 输入以下语句创建 player 标签:

    nebula> CREATE TAG player(name string, age int);
    
  2. 输入以下语句创建 team 标签:

    nebula> CREATE TAG team(name string);
    
  3. 输入以下语句创建 follow 边类型:

    nebula> CREATE EDGE follow(degree int);
    
  4. 输入以下语句创建 serve 边类型:

    nebula> CREATE EDGE serve(start_year int, end_year int);
    
  5. 现在,您可以查看刚刚创建的标签和边类型。

    5.1 要获取刚创建的标签,请输入以下语句:

    nebula> SHOW TAGS;
    

    返回以下信息:

    ============
    | Name     |
    ============
    | player   |
    ------------
    | team     |
    ------------
    

    5.2 要显示刚创建的边类型,请输入以下语句:

    nebula> SHOW EDGES;
    

    返回以下信息:

    ==========
    | Name   |
    ==========
    | serve  |
    ----------
    | follow |
    ----------
    

    5.3 要显示 player 标签的属性,请输入以下语句:

    nebula> DESCRIBE TAG player;
    

    返回以下信息:

    ===================
    | Field  | Type   |
    ===================
    | name   | string |
    -------------------
    | age    | int    |
    -------------------
    

    5.4 要获取 follow 边类型的属性,请输入以下语句:

    nebula> DESCRIBE EDGE follow;
    

    返回以下信息:

    =====================
    | Field    | Type   |
    =====================
    | degree   | int    |
    ---------------------
    

增删改查

插入数据

您可以根据示意图中的关系插入点和边数据。

插入点

INSERT VERTEX 语句通过指定点的标签、属性、点 ID 和属性值来插入一个点。

您可以通过以下语句插入点:

nebula> INSERT VERTEX player(name, age) VALUES 100:("Tim Duncan", 42);
nebula> INSERT VERTEX player(name, age) VALUES 101:("Tony Parker", 36);
nebula> INSERT VERTEX player(name, age) VALUES 102:("LaMarcus Aldridge", 33);
nebula> INSERT VERTEX team(name) VALUES 200:("Warriors");
nebula> INSERT VERTEX team(name) VALUES 201:("Nuggets");
nebula> INSERT VERTEX player(name, age) VALUES 121:("Useless", 60);

注意

  1. 在上面插入的点中,关键词 VALUES 之后的数字是点的 ID(缩写为 VID, int64)。每个图空间中的 VID 必须是唯一的。

  2. 最后插入的点(VID: 121)将在下文删除数据部分中删除。

  3. 如果您想一次批量插入同类型的点,可以执行以下语句:

    nebula> INSERT VERTEX player(name, age) VALUES 100:("Tim Duncan", 42), \
            101:("Tony Parker", 36), 102:("LaMarcus Aldridge", 33);
    

    反除号 \ 用于实现多行语句。

插入边

INSERT EDGE 语句通过指定边类型名称、属性、起始点VID和目标点VID以及属性值来插入边。

您可以通过以下语句插入边:

nebula> INSERT EDGE follow(degree) VALUES 100 -> 101:(95);
nebula> INSERT EDGE follow(degree) VALUES 100 -> 102:(90);
nebula> INSERT EDGE follow(degree) VALUES 102 -> 101:(75);
nebula> INSERT EDGE serve(start_year, end_year) VALUES 100 -> 200:(1997, 2016);
nebula> INSERT EDGE serve(start_year, end_year) VALUES 101 -> 201:(1999, 2018);

同样的:如果您想一次批量插入多条同类型的边,可以执行以下语句:

nebula> INSERT EDGE follow(degree) VALUES 100 -> 101:(95), 100 -> 102:(90), 102 -> 101:(75);

读取数据

Nebula Graph 中插入数据后,您可以从图空间中查询到之前已经插入的数据。

FETCH PROP ON 语句从图空间检索数据。如果要获取点的数据,则必须指定点的标签和点 VID;如果要获取边数据,则必须指定边的类型、起始点 VID 和目标点 VID。

例如,要获取 VID100 的选手的数据,请输入以下语句:

nebula> FETCH PROP ON player 100;

返回以下信息:

=======================================
| VertexID | player.name | player.age |
=======================================
| 100      | Tim Duncan  | 42         |
---------------------------------------

例如,要获取 VID 100VID 200 之间的类型为 serve 的边上的属性,请输入以下语句:

nebula> FETCH PROP ON serve 100 -> 200;

返回以下信息:

=============================================================================
| serve._src | serve._dst | serve._rank | serve.start_year | serve.end_year |
=============================================================================
| 100        | 200        | 0           | 1997             | 2016           |
-----------------------------------------------------------------------------

更新数据

您可以更新刚插入的点和边数据。

更新点数据

UPDATE VERTEX 语句用于更新点的属性。

指定要更新的点 VID,然后在等号右侧为其分配新值来更新点的全部或者部分属性。

以下示例说明如何将 VID 100 的属性 nameTim Duncan 更改为 Tim

输入以下语句更新 name 值:

nebula> UPDATE VERTEX 100 SET player.name = "Tim";

要检查 name 值是否已更新,请输入以下语句:

nebula> FETCH PROP ON player 100;

返回以下信息:

=======================================
| VertexID | player.name | player.age |
=======================================
| 100      | Tim         | 42         |
---------------------------------------

更新边数据

类似的,UPDATE EDGE 语句用于更新边的属性。

通过指定边的起始点 VID 和目标点 VID,然后在等号右侧为其分配新值来更新边的属性。

以下示例展示了如何更改 VID 100VID 101 之间,类型为 follow 的边的属性。

现在,我们将 degree 的值增加 1

nebula> UPDATE EDGE 100 -> 101 OF follow SET degree = follow.degree + 1;

要检查 degree 的值是否已更新,请输入以下语句:

nebula> FETCH PROP ON follow 100 -> 101;

返回以下信息:

============================================================
| follow._src | follow._dst | follow._rank | follow.degree |
============================================================
| 100         | 101         | 0            | 96            |
------------------------------------------------------------

UPSERT

UPSERT 用于插入新的点或边或更新现有的点或边。如果点或边不存在,则会新建该点或边。UPSERTINSERTUPDATE 的组合。

例如:

nebula> INSERT VERTEX player(name, age) VALUES 111:("Ben Simmons", 22); -- 插入一个新点。
nebula> UPSERT VERTEX 111 SET player.name = "Dwight Howard", player.age = $^.player.age + 11 WHEN $^.player.name == "Ben Simmons" && $^.player.age > 20 YIELD $^.player.name AS Name, $^.player.age AS Age; -- 对该点进行 UPSERT 操作。
=======================
| Name          | Age |
=======================
| Dwight Howard | 33  |
-----------------------

详情查看 UPSERT 文档

删除数据

删除点

DELETE VERTEX 语句通过指定点 VID 来删除点。同时也会删除该点的所有标签,以及和该点相邻的所有入边和出边

要删除 VID 121 的点,请输入以下语句:

nebula> DELETE VERTEX 121;

要检查是否删除了该点,请输入以下语句;

nebula> FETCH PROP ON player 121;
Execution succeeded (Time spent: 1571/1910 us)

上面返回结果为空,表示查询操作成功,但是由于数据已被删除,未能从图空间中查询到任何数据。

删除边

您可以从图空间中删除任何边。DELETE EDGE 语句通过指定边的类型以及起始点 VID 和目标点 VID 来删除边。

要删除 VID 100VID 200 之间的类型为 follow 的边,请输入以下语句:

nebula> DELETE EDGE follow 100 -> 200;

创建索引

您可以使用 CREATE INDEX 为已有 Tag/Edge-type 创建索引。

nebula> CREATE TAG INDEX player_index_0 on player(name);

上述语句在所有标签为 player 的点上为属性 name 创建了一个索引。

索引会影响写性能,第一次批量导入的时候,建议先导入数据,再批量重构索引。不推荐带索引批量导入,这样写性能会非常差。

nebula> REBUILD TAG INDEX player_index_0 OFFLINE;

详情参看索引文档

查询示例

本节提供了更多查询示例供您参考。

示例1

查询球员 VID 100 关注 (follow) 的其他球员。

输入以下语句:

nebula> GO FROM 100 OVER follow;

返回以下信息:

===============
| follow._dst |
===============
| 101         |
---------------
| 102         |
---------------

示例2

查询球员 VID 100 关注的球员,被关注球员年龄需大于 35 岁。 返回其姓名和年龄,并取别名为 TeammateAge

输入以下语句:

nebula> GO FROM 100 OVER follow WHERE $$.player.age >= 35 \
        YIELD $$.player.name AS Teammate, $$.player.age AS Age;

返回以下信息:

=====================
| Teammate    | Age |
=====================
| Tony Parker | 36  |
---------------------

这里

  • YIELD 指定希望从查询中返回的结果。
  • $$ 表示边上的目的点。
  • \ 表示换行符。

示例3

查询球员 100 关注的球员所效力的球队。 有两种方法可获得相同的结果:

  1. 使用 管道(|) 来组合两个查询语句

    nebula> GO FROM 100 OVER follow YIELD follow._dst AS id | \
            GO FROM $-.id OVER serve YIELD $$.team.name AS Team, \
            $^.player.name AS Player;
    

    返回如下信息:

    ===============================
    | Team    | Player            |
    ===============================
    | Nuggets | Tony Parker       |
    -------------------------------
    

    这里

    $^ 表示边的起始点。

    | 表示管道。

    $- 表示输入流。上一个查询的输出(id)作为下一个查询的输入($-.id)

  2. 使用自定义的变量来组合两个查询语句

    nebula> $var = GO FROM 100 OVER follow YIELD follow._dst AS id; \
            GO FROM $var.id OVER serve YIELD $$.team.name AS Team, \
            $^.player.name AS Player;
    

    返回以下信息:

    ===============================
    | Team    | Player            |
    ===============================
    | Nuggets | Tony Parker       |
    -------------------------------
    

当一条组合语句被整体提交给服务器后,该语句内的自定义变量就已结束生命周期。

示例 4

如果您已为数据创建索引且重构索引,则可以使用 LOOKUP ON 关键字进行属性查询。

nebula> CREATE TAG INDEX player_index_0 on player(name);
nebula> REBUILD TAG INDEX player_index_0 OFFLINE;

请参考索引文档创建索引。

如下示例返回名称为 Tony Parker,标签为 player 的点。

nebula> LOOKUP ON player WHERE player.name == "Tony Parker" \
YIELD player.name, player.age;
=======================================
| VertexID | player.name | player.age |
=======================================
| 101      | Tony Parker | 36         |
---------------------------------------

详情参考 LOOKUP 文档

示例 5

SUBMIT JOB COMPACT 命令触发长耗时的 RocksDB compact 操作。该命令运行期间会有大量 IO 操作,命令执行完成后(job 状态为 stopped,见下方示例)可以提升读性能。

示例返回结果如下:

nebula> SUBMIT JOB COMPACT;
==============
| New Job Id |
==============
| 40         |
--------------

并且,命令 SHOW JOBS 用于列出所有未过期的作业信息。示例返回结果如下:

nebula> SHOW JOBS;
=============================================================================
| Job Id | Command       | Status   | Start Time        | Stop Time         |
=============================================================================
| 22     | flush test2   | failed   | 12/06/19 14:46:22 | 12/06/19 14:46:22 |
-----------------------------------------------------------------------------
| 23     | compact test2 | stopped  | 12/06/19 15:07:09 | 12/06/19 15:07:33 |
-----------------------------------------------------------------------------
| 24     | compact test2 | stopped  | 12/06/19 15:07:11 | 12/06/19 15:07:20 |
-----------------------------------------------------------------------------
| 25     | compact test2 | stopped  | 12/06/19 15:07:13 | 12/06/19 15:07:24 |
-----------------------------------------------------------------------------

更多关于 COMPACTJOB 命令,参考作业管理(flush 和 compact)

批量执行

通常测试时需要执行多条数据来准备环境,可以将所有语句放入一个 .ngql 文件中,如下所示。

CREATE SPACE nba(partition_num=10, replica_factor=1);
USE nba;
CREATE TAG player(name string, age int);
CREATE TAG team(name string);
CREATE EDGE follow(degree int);
CREATE EDGE serve(start_year int, end_year int);

在服务器:

$ cat schema.ngql | ./bin/nebula -u <user> -p <password>

或者 Docker

$ cat nba.ngql | sudo docker run --rm -i --network=host \
vesoft/nebula-console:nightly --addr=<127.0.0.1> --port=<3699>

这里

  • 必须将 --addr 和 --port 更改为您自己的 IP 地址和端口号。
  • 可以在这里下载 nba.ngql 文件。

后续操作

在进一步使用 Nebula Graph 之前,请阅读以下文档。这些文档会回答你关于 Nebula Graph 的大多数疑问。如果在阅读这些文档后,你的疑问仍然存在,请前往我们的 官方论坛 提问。

最后

如果您在使用 Nebula Graph 的过程中遇到任何问题,请前往我们的 官方论坛 提问,将有专门的值班开发人员为您解答问题。

如果您完成了本手册的全部操作,认为 Nebula Graph 是一款值得尝试的图数据库产品,恳请移步 GitHub 留下您珍贵的一颗星,这将鼓舞我们继续向前。