导入 HIVE 数据

本文以一个示例说明如何使用 Exchange 将存储在 HIVE 的数据导入 Nebula Graph。

数据集

本文以美国 Stanford Network Analysis Platform (SNAP) 提供的 Social Network: MOOC User Action Dataset 以及由公开网络上获取的不重复的 97 个课程名称作为示例数据集，包括：

  • 两类点（user 和 course），共计 7,144 个点。
  • 一种关系（action），共计 411,749 条边。

详细的数据集，您可以从 nebula-web-docker 仓库中下载。

在本示例中，该数据集已经存入 HIVE 中名为 mooc 的数据库中，以 users、courses 和 actions 三个表存储了所有点和边的信息。以下为各个表的结构。

  1. scala> sql("describe mooc.users").show
  2. +--------+---------+-------+
  3. |col_name|data_type|comment|
  4. +--------+---------+-------+
  5. |  userid|   bigint|   null|
  6. +--------+---------+-------+
  8. scala> sql("describe mooc.courses").show
  9. +----------+---------+-------+
  10. |  col_name|data_type|comment|
  11. +----------+---------+-------+
  12. |  courseid|   bigint|   null|
  13. |coursename|   string|   null|
  14. +----------+---------+-------+
  16. scala> sql("describe mooc.actions").show
  17. +--------+---------+-------+
  18. |col_name|data_type|comment|
  19. +--------+---------+-------+
  20. |actionid|   bigint|   null|
  21. |   srcid|   bigint|   null|
  22. |   dstid|   string|   null|
  23. |duration|   double|   null|
  24. |feature0|   double|   null|
  25. |feature1|   double|   null|
  26. |feature2|   double|   null|
  27. |feature3|   double|   null|
  28. |   label|  boolean|   null|
  29. +--------+---------+-------+

说明：Hive 的 bigint 与 Nebula Graph 的 int 对应。

环境配置

本文示例在 MacOS 下完成，以下是相关的环境配置信息：

  • 硬件规格：

    • CPU：1.7 GHz Quad-Core Intel Core i7
    • 内存：16 GB

  • Spark：2.4.7，单机版

  • Hadoop：2.9.2，伪分布式部署

  • HIVE：2.3.7，Hive Metastore 数据库为 MySQL 8.0.22

  • Nebula Graph：V1.2.0，使用 Docker Compose 部署。详细信息，参考 使用 Docker Compose 部署 Nebula Graph

前提条件

开始导入数据之前，您需要确认以下信息：

  • 已经完成 Exchange 编译。详细信息，参考 编译 Exchange。本示例中使用 Exchange v1.2.1。

  • 已经安装 Spark。

  • 已经安装并开启 Hadoop 服务，并已启动 Hive Metastore 数据库（本示例中为 MySQL）。

  • 已经部署并启动 Nebula Graph，并获取：

    • Graph 服务、Meta 服务所在机器的 IP 地址和端口信息。
    • Nebula Graph 数据库的拥有写权限的用户名及其密码。

  • 在 Nebula Graph 中创建图数据模式（Schema）所需的所有信息，包括标签和边类型的名称、属性等。

操作步骤

步骤 1. 在 Nebula Graph 中创建 Schema

按以下步骤在 Nebula Graph 中创建 Schema：

  1. 确认 Schema 要素：Nebula Graph 中的 Schema 要素如下表所示。

    要素名称属性
    标签（Tag）useruserId int
    标签（Tag）coursecourseId int, courseName string
    边类型（Edge Type）actionactionId int, duration double, label bool, feature0 double, feature1 double, feature2 double, feature3 double

  2. 在 Nebula Graph 里创建一个图空间 hive，并创建一个 Schema，如下所示。

    1. -- 创建图空间
    2. CREATE SPACE hive(partition_num=10, replica_factor=1);
    4. -- 选择图空间 hive
    5. USE hive;
    7. -- 创建标签 user
    8. CREATE TAG user(userId int);
    10. -- 创建标签 course
    11. CREATE TAG course(courseId int, courseName string);
    13. -- 创建边类型 action
    14. CREATE EDGE action (actionId int, duration double, label bool, feature0 double, feature1 double, feature2 double, feature3 double);

关于 Nebula Graph 构图的更多信息，参考《Nebula Graph Database 手册》的 快速开始。

步骤 2. 使用 Spark SQL 确认 HIVE SQL 语句

启动 spark-shell 环境后，依次运行以下语句，确认 Spark 能读取 HIVE 中的数据。

  1. scala> sql("select userid from mooc.users").show
  2. scala> sql("select courseid, coursename from mooc.courses").show
  3. scala> sql("select actionid, srcid, dstid, duration, feature0, feature1, feature2, feature3, label from mooc.actions").show

以下为 mooc.actions 表中读出的结果。

  1. +--------+-----+--------------------+--------+------------+------------+-----------+-----------+-----+
  2. |actionid|srcid|               dstid|duration|    feature0|    feature1|   feature2|   feature3|label|
  3. +--------+-----+--------------------+--------+------------+------------+-----------+-----------+-----+
  4. |       0|    0|Environmental Dis...|     0.0|-0.319991479|-0.435701433|0.106783779|-0.06730924|false|
  5. |       1|    0|  History of Ecology|     6.0|-0.319991479|-0.435701433|0.106783779|-0.06730924|false|
  6. |       2|    0|      Women in Islam|    41.0|-0.319991479|-0.435701433|0.106783779|-0.06730924|false|
  7. |       3|    0|  History of Ecology|    49.0|-0.319991479|-0.435701433|0.106783779|-0.06730924|false|
  8. |       4|    0|      Women in Islam|    51.0|-0.319991479|-0.435701433|0.106783779|-0.06730924|false|
  9. |       5|    0|Legacies of the A...|    55.0|-0.319991479|-0.435701433|0.106783779|-0.06730924|false|
  10. |       6|    0|          ITP Core 2|    59.0|-0.319991479|-0.435701433|0.106783779|-0.06730924|false|
  11. |       7|    0|The Research Pape...|    62.0|-0.319991479|-0.435701433|0.106783779|-0.06730924|false|
  12. |       8|    0|        Neurobiology|    65.0|-0.319991479|-0.435701433|0.106783779|-0.06730924|false|
  13. |       9|    0|           Wikipedia|   113.0|-0.319991479|-0.435701433|1.108826104|12.77723482|false|
  14. |      10|    0|Media History and...|   226.0|-0.319991479|-0.435701433|0.607804941|149.4512115|false|
  15. |      11|    0|             WIKISOO|   974.0|-0.319991479|-0.435701433|1.108826104|3.344522776|false|
  16. |      12|    0|Environmental Dis...|  1000.0|-0.319991479|-0.435701433|0.106783779|-0.06730924|false|
  17. |      13|    0|             WIKISOO|  1172.0|-0.319991479|-0.435701433|1.108826104|1.136866766|false|
  18. |      14|    0|      Women in Islam|  1182.0|-0.319991479|-0.435701433|0.106783779|-0.06730924|false|
  19. |      15|    0|  History of Ecology|  1185.0|-0.319991479|-0.435701433|0.106783779|-0.06730924|false|
  20. |      16|    0|Human Development...|  1687.0|-0.319991479|-0.435701433|0.106783779|-0.06730924|false|
  21. |      17|    1|Human Development...|  7262.0|-0.319991479|-0.435701433|0.106783779|-0.06730924|false|
  22. |      18|    1|  History of Ecology|  7266.0|-0.319991479|-0.435701433|0.106783779|-0.06730924|false|
  23. |      19|    1|      Women in Islam|  7273.0|-0.319991479|-0.435701433|0.607804941|0.936170765|false|
  24. +--------+-----+--------------------+--------+------------+------------+-----------+-----------+-----+
  25. only showing top 20 rows

步骤 3. 修改配置文件

完成 Exchange 编译后，进入 nebula-java/tools/exchange 目录，根据 target/classes/application.conf 文件修改 HIVE 数据源相关的配置文件。在本示例中，文件被重命名为 hive_application.conf。以下仅详细说明点和边数据的配置信息，本次示例中未使用的配置项已被注释，但是提供了配置说明。Spark 和 Nebula Graph 相关配置，参考 Spark 参数和 Nebula Graph 参数。

  1. {
  2.   # Spark 相关配置
  3.   spark: {
  4.     app: {
  5.       name: Spark Writer
  6.     }
  7.     driver: {
  8.       cores: 1
  9.       maxResultSize: 1G
  10.     }
  11.     cores {
  12.       max: 16
  13.     }
  14.   }
  15.   # Nebula Graph 相关配置
  16.   nebula: {
  17.     address:{
  18.       # 以下为 Nebula Graph 的 Graph 服务和 Meta 服务所在机器的 IP 地址及端口
  19.       # 如果有多个地址，格式为 "ip1:port","ip2:port","ip3:port"
  20.       # 不同地址之间以英文逗号 (,) 隔开
  21.       graph:["127.0.0.1:3699"]
  22.       meta:["127.0.0.1:45500"]
  23.     }
  24.     # 填写的账号必须拥有 Nebula Graph 相应图空间的写数据权限
  25.     user: user
  26.     pswd: password
  27.     # 填写 Nebula Graph 中需要写入数据的图空间名称
  28.     space: hive
  29.     connection {
  30.       timeout: 3000
  31.       retry: 3
  32.     }
  33.     execution {
  34.       retry: 3
  35.     }
  36.     error: {
  37.       max: 32
  38.       output: /tmp/errors
  39.     }
  40.     rate: {
  41.       limit: 1024
  42.       timeout: 1000
  43.     }
  44.   }
  45.   # 处理标签
  46.   tags: [
  47.     # 设置标签相关信息
  48.     {
  49.       # Nebula Graph 中对应的标签名称。
  50.       name: user
  51.       type: {
  52.         # 指定数据源文件格式，设置为 hive。
  53.         source: hive
  54.         # 指定点数据导入 Nebula Graph 的方式，
  55.         # 可以设置为：client（以客户端形式导入）和 sst（以 SST 文件格式导入）。
  56.         # 关于 SST 文件导入配置，参考文档：导入 SST 文件（https://
  57.         # docs.nebula-graph.com.cn/nebula-exchange/
  58.         # use-exchange/ex-ug-import-sst/）。
  59.         sink: client
  60.       }
  62.       # 设置读取数据库 mooc 中 users 表数据的 SQL 语句
  63.       exec: "select userid from mooc.users"
  65.       # 在 fields 里指定 users 表中的列名称，其对应的 value
  66.       # 会作为 Nebula Graph 中指定属性 userId (nebula.fields) 的数据源
  67.       # fields 和 nebula.fields 里的配置必须一一对应
  68.       # 如果需要指定多个列名称，用英文逗号（,）隔开
  69.       fields: [userid]
  70.       nebula.fields: [userId]
  72.       # 指定表中某一列数据为 Nebula Graph 中点 VID 的来源。
  73.       # vertex.field 的值必须与上述 fields 中的列名保持一致。
  74.       # 如果数据不是 int 类型，则添加 vertex.policy 指定 VID 映射策略，建议设置为 "hash"，参考以下 course 标签的设置。
  75.       vertex: userid
  77.       # 单次写入 Nebula Graph 的最大点数据量。
  78.       batch: 256
  80.       # Spark 分区数量
  81.       partition: 32
  83.       # isImplicit 的设置说明参考：https://github.com/vesoft-inc/nebula-java/
  84.       # blob/v1.0/tools/exchange/src/main/resources/application.conf
  85.       isImplicit: true
  86.     }
  87.     {
  88.       name: course
  89.       type: {
  90.         source: hive
  91.         sink: client
  92.       }
  93.       exec: "select courseid, coursename from mooc.courses"
  94.       fields: [courseid, coursename]
  95.       nebula.fields: [courseId, courseName]
  97.       # 指定表中某一列数据为 Nebula Graph 中点 VID 的来源。
  98.       # vertex.field 的值必须与上述 fields 中的列名保持一致。
  99.       # 如果数据不是 int 类型，则添加 vertex.policy 指定 VID 映射策略，建议设置为 "hash"。
  100.       vertex: {
  101.         field: coursename
  102.         policy: "hash"
  103.       }
  104.       batch: 256
  105.       partition: 32
  106.       isImplicit: true
  107.     }
  109.   ]
  111.   # 处理边数据
  112.   edges: [
  113.     # 设置边类型 action 相关信息
  114.     {
  115.       # Nebula Graph 中对应的边类型名称。
  116.       name: action
  118.       type: {
  119.         # 指定数据源文件格式，设置为 hive。
  120.         source: hive
  122.         # 指定边数据导入 Nebula Graph 的方式，
  123.         # 可以设置为：client（以客户端形式导入）和 sst（以 SST 文件格式导入）。
  124.         # 关于 SST 文件导入配置，参考文档：导入 SST 文件（https://
  125.         # docs.nebula-graph.com.cn/nebula-exchange/
  126.         # use-exchange/ex-ug-import-sst/）。
  127.         sink: client
  128.       }
  130.       # 设置读取数据库 mooc 中 actions 表数据的 SQL 语句
  131.       exec: "select actionid, srcid, dstid, duration, feature0, feature1, feature2, feature3, label from mooc.actions"
  133.       # 在 fields 里指定 actions 表中的列名称，其对应的 value
  134.       # 会作为 Nebula Graph 中 action 的属性（nebula.fields）值来源
  135.       # fields 和 nebula.fields 里的配置必须一一对应
  136.       # 如果需要指定多个列名称，用英文逗号（,）隔开
  137.       fields: [actionid, duration, feature0, feature1, feature2, feature3, label]
  138.       nebula.fields: [actionId, duration, feature0, feature1, feature2, feature3, label]
  140.       # 在 source 里，将 actions 表中某一列作为边起点数据源
  141.       # 在 target 里，将 actions 表中某一列作为边终点数据源
  142.       # 如果数据源是 int 或 long 类型，直接指定列名
  143.       # 如果数据源不是 int 类型，则添加 vertex.policy 指定 VID 映射策略，建议设置为 "hash"
  144.       source: srcid
  145.       target: {
  146.         field: dstid
  147.         policy: "hash"
  148.       }
  150.       # 单次写入 Nebula Graph 的最大点数据量。
  151.       batch: 256
  153.       # Spark 分区数量
  154.       partition: 32
  155.     }
  156.   ]
  157. }

步骤 4. （可选）检查配置文件是否正确

完成配置后，运行以下命令检查配置文件格式是否正确。关于参数的说明，参考 导入命令参数。

  1. $SPARK_HOME/bin/spark-submit --master "local" --class com.vesoft.nebula.tools.importer.Exchange /path/to/exchange-1.2.1.jar -c /path/to/conf/hive_application.conf -h -D

步骤 5. 向 Nebula Graph 导入数据

运行以下命令将 HIVE 中的数据导入到 Nebula Graph 中。关于参数的说明，参考 导入命令参数。

  1. $SPARK_HOME/bin/spark-submit --master "local" --class com.vesoft.nebula.tools.importer.Exchange /path/to/exchange-1.2.1.jar -c /path/to/conf/hive_application.conf -h

步骤 6. （可选）验证数据

您可以在 Nebula Graph 客户端（例如 Nebula Graph Studio）里执行语句，确认数据是否已导入，例如：

  1. GO FROM 1 OVER action;

如果返回边终点（action._dst）即表明数据已导入。

您也可以使用 db_dump 工具统计数据是否已经全部导入。详细的使用信息参考 Dump Tool。

步骤 7. （可选）在 Nebula Graph 中重构索引

导入数据后，您可以在 Nebula Graph 中重新创建并重构索引。详细信息，参考《Nebula Graph Database 手册》。