快速入门

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

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

安装

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

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

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

数据建模

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

image

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

创建并使用图空间

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

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

  1. 检查集群机器状态:

    1. nebula> SHOW HOSTS;
    2. ================================================================================================
    3. | Ip | Port | Status | Leader count | Leader distribution | Partition distribution |
    4. ================================================================================================
    5. | 192.168.8.210 | 44500 | online | | | |
    6. ------------------------------------------------------------------------------------------------
    7. | 192.168.8.211 | 44500 | online | | | |
    8. ------------------------------------------------------------------------------------------------

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

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

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

    这里:

    • partition_num:指定一个副本中的分区数。通常为全集群硬盘数量的 5 倍。

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

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

      1. nebula> SHOW HOSTS;
      2. =============================================================================================================
      3. | Ip | Port | Status | Leader count | Leader distribution | Partition distribution |
      4. =============================================================================================================
      5. | 192.168.8.210 | 44500 | online | 8 | basketballplayer: 8 | test: 8 |
      6. -------------------------------------------------------------------------------------------------------------
      7. | 192.168.8.211 | 44500 | online | 2 | basketballplayer: 2 | test: 2 |
      8. -------------------------------------------------------------------------------------------------------------

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

      1. nebula> BALANCE LEADER;
      2. =============================================================================================================
      3. | Ip | Port | Status | Leader count | Leader distribution | Partition distribution |
      4. =============================================================================================================
      5. | 192.168.8.210 | 44500 | online | 5 | basketballplayer: 5 | test: 5 |
      6. -------------------------------------------------------------------------------------------------------------
      7. | 192.168.8.211 | 44500 | online | 5 | basketballplayer: 5 | test: 5 |
      8. -------------------------------------------------------------------------------------------------------------

      具体解释可以见这里

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

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

    1. nebula> SHOW SPACES;

    返回以下信息:

    1. ========
    2. | Name |
    3. ========
    4. | basketballplayer |
    5. --------

定义数据的 Schema

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

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

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

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

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

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

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

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

    1. nebula> SHOW TAGS;

    返回以下信息:

    1. ============
    2. | Name |
    3. ============
    4. | player |
    5. ------------
    6. | team |
    7. ------------

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

    1. nebula> SHOW EDGES;

    返回以下信息:

    1. ==========
    2. | Name |
    3. ==========
    4. | serve |
    5. ----------
    6. | follow |
    7. ----------

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

    1. nebula> DESCRIBE TAG player;

    返回以下信息:

    1. ===================
    2. | Field | Type |
    3. ===================
    4. | name | string |
    5. -------------------
    6. | age | int |
    7. -------------------

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

    1. nebula> DESCRIBE EDGE follow;

    返回以下信息:

    1. =====================
    2. | Field | Type |
    3. =====================
    4. | degree | int |
    5. ---------------------

创建索引

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

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

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

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

详情参看索引文档

增删改查

插入数据

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

插入点

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

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

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

注意

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

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

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

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

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

插入边

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

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

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

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

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

读取数据

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

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

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

  1. nebula> FETCH PROP ON player 100;

返回以下信息:

  1. =======================================
  2. | VertexID | player.name | player.age |
  3. =======================================
  4. | 100 | Tim Duncan | 42 |
  5. ---------------------------------------

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

  1. nebula> FETCH PROP ON serve 100 -> 200;

返回以下信息:

  1. =============================================================================
  2. | serve._src | serve._dst | serve._rank | serve.start_year | serve.end_year |
  3. =============================================================================
  4. | 100 | 200 | 0 | 1997 | 2016 |
  5. -----------------------------------------------------------------------------

更新数据

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

更新点数据

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

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

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

输入以下语句更新 name 值:

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

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

  1. nebula> FETCH PROP ON player 100;

返回以下信息:

  1. =======================================
  2. | VertexID | player.name | player.age |
  3. =======================================
  4. | 100 | Tim | 42 |
  5. ---------------------------------------

更新边数据

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

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

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

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

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

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

  1. nebula> FETCH PROP ON follow 100 -> 101;

返回以下信息:

  1. ============================================================
  2. | follow._src | follow._dst | follow._rank | follow.degree |
  3. ============================================================
  4. | 100 | 101 | 0 | 96 |
  5. ------------------------------------------------------------

UPSERT

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

例如:

  1. nebula> INSERT VERTEX player(name, age) VALUES 111:("Ben Simmons", 22); -- 插入一个新点。
  2. 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 操作。
  3. =======================
  4. | Name | Age |
  5. =======================
  6. | Dwight Howard | 33 |
  7. -----------------------

详情查看 UPSERT 文档

删除数据

删除点

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

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

  1. nebula> DELETE VERTEX 121;

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

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

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

删除边

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

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

  1. nebula> DELETE EDGE follow 100 -> 200;

其他

查询示例

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

示例1

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

输入以下语句:

  1. nebula> GO FROM 100 OVER follow;

返回以下信息:

  1. ===============
  2. | follow._dst |
  3. ===============
  4. | 101 |
  5. ---------------
  6. | 102 |
  7. ---------------

示例2

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

输入以下语句:

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

返回以下信息:

  1. =====================
  2. | Teammate | Age |
  3. =====================
  4. | Tony Parker | 36 |
  5. ---------------------

这里

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

示例3

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

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

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

    返回如下信息:

    1. ===============================
    2. | Team | Player |
    3. ===============================
    4. | Nuggets | Tony Parker |
    5. -------------------------------

    这里

    $^ 表示边的起始点。

    | 表示管道。

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

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

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

    返回以下信息:

    1. ===============================
    2. | Team | Player |
    3. ===============================
    4. | Nuggets | Tony Parker |
    5. -------------------------------

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

示例 4

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

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

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

  1. nebula> LOOKUP ON player WHERE player.name == "Tony Parker" \
  2. YIELD player.name, player.age;
  3. =======================================
  4. | VertexID | player.name | player.age |
  5. =======================================
  6. | 101 | Tony Parker | 36 |
  7. ---------------------------------------

详情参考 LOOKUP 文档

批量执行

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

  1. CREATE SPACE basketballplayer(partition_num=10, replica_factor=1);
  2. USE basketballplayer;
  3. CREATE TAG player(name string, age int);
  4. CREATE TAG team(name string);
  5. CREATE EDGE follow(degree int);
  6. CREATE EDGE serve(start_year int, end_year int);

在服务器:

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

或者 Docker

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

这里

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

批量导入

如果您要插入数百万条记录,建议使用 csv 导入工具Spark 导入工具

最后

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

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