导入SST文件数据

本文以一个示例说明如何将数据源的数据生成SST（Sorted String Table）文件并保存在HDFS上，然后导入Nebula Graph，示例数据源是CSV文件。

注意事项

  • 仅Linux系统支持导入SST文件。

  • 不支持属性的Default值。

背景信息

Exchange支持两种数据导入模式：

  • 直接将数据源的数据通过nGQL语句的形式导入Nebula Graph。

  • 将数据源的数据生成SST文件，然后借助Console将SST文件导入Nebula Graph。

下文将介绍生成SST文件并用其导入数据的适用场景、实现方法、前提条件、操作步骤等内容。

适用场景

  • 适合在线业务，因为生成时几乎不会影响业务（只是读取Schema），导入速度快。

    Caution

    虽然导入速度快，但是导入期间（大约10秒）会阻塞对应空间的写操作，建议在业务低峰期进行导入。

  • 适合数据源数据量较大的场景，导入速度快。

实现方法

Nebula Graph底层使用RocksDB作为键值型存储引擎。RocksDB是基于硬盘的存储引擎，提供了一系列API用于创建及导入SST格式的文件，有助于快速导入海量数据。

SST文件是一个内部包含了任意长度的有序键值对集合的文件，用于高效地存储大量键值型数据。生成SST文件的整个过程主要由Exchange的Reader、sstProcessor和sstWriter完成。整个数据处理过程如下：

  1. Reader从数据源中读取数据。

  2. sstProcessor根据Nebula Graph的Schema信息生成SST文件，然后上传至HDFS。SST文件的格式请参见数据存储格式。

  3. sstWriter打开一个文件并插入数据。生成SST文件时，Key必须按照顺序写入。

  4. 生成SST文件之后，RocksDB通过IngestExternalFile()方法将SST文件导入到Nebula Graph中。例如：

    1. IngestExternalFileOptions ifo;
    2. # 导入两个SST文件
    3. Status s = db_->IngestExternalFile({"/home/usr/file1.sst", "/home/usr/file2.sst"}, ifo);
    4. if (!s.ok()) {
    5.   printf("Error while adding file %s and %s, Error %s\n",
    6.          file_path1.c_str(), file_path2.c_str(), s.ToString().c_str());
    7.   return 1;
    8. }

    调用IngestExternalFile()方法时，RocksDB默认会将文件拷贝到数据目录，并且阻塞RocksDB写入操作。如果SST文件中的键范围覆盖了Memtable键的范围，则将Memtable落盘（flush）到硬盘。将SST文件放置在LSM树最优位置后，为文件分配一个全局序列号，并打开写操作。

数据集

本文以basketballplayer数据集为例。

环境配置

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

  • 硬件规格：

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

  • Spark：2.4.7 单机版

  • Hadoop：2.9.2 伪分布式部署

  • Nebula Graph：2.5.1。

前提条件

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

  • 已经安装部署Nebula Graph 2.5.1并获取如下信息：

    • Graph服务和Meta服务的的IP地址和端口。

    • 拥有Nebula Graph写权限的用户名和密码。

    • Meta服务配置文件中的--ws_storage_http_port和Storage服务配置文件中的--ws_http_port一致。例如都为19779。

    • Graph服务配置文件中的--ws_meta_http_port和Meta服务配置文件中的--ws_http_port一致。例如都为19559。

    • Schema的信息，包括Tag和Edge type的名称、属性等。

  • 已经编译Exchange，或者直接下载编译完成的.jar文件。本示例中使用Exchange 2.5.1。

  • 已经安装Spark。

  • 已经安装JDK 1.8或以上版本，并配置环境变量JAVA_HOME。

  • 确认Hadoop服务在所有部署Storage服务的机器上运行正常。

    Note

    • 如果需要生成其他数据源的SST文件，请参见相应数据源的文档，查看前提条件部分。

    • 如果只需要生成SST文件，不需要在部署Storage服务的机器上安装Hadoop服务。

操作步骤

步骤 1：在Nebula Graph中创建Schema

分析CSV文件中的数据，按以下步骤在Nebula Graph中创建Schema：

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

    要素名称属性
    Tagplayername string, age int
    Tagteamname string
    Edge Typefollowdegree int
    Edge Typeservestart_year int, end_year int

  2. 使用Nebula Console创建一个图空间basketballplayer，并创建一个Schema，如下所示。

    1. ## 创建图空间
    2. nebula> CREATE SPACE basketballplayer \
    3.         (partition_num = 10, \
    4.         replica_factor = 1, \
    5.         vid_type = FIXED_STRING(30));
    7. ## 选择图空间basketballplayer
    8. nebula> USE basketballplayer;
    10. ## 创建Tag player
    11. nebula> CREATE TAG player(name string, age int);
    13. ## 创建Tag team
    14. nebula> CREATE TAG team(name string);
    16. ## 创建Edge type follow
    17. nebula> CREATE EDGE follow(degree int);
    19. ## 创建Edge type serve
    20. nebula> CREATE EDGE serve(start_year int, end_year int);

更多信息，请参见快速开始。

步骤 2：处理CSV文件

确认以下信息：

  1. 处理CSV文件以满足Schema的要求。

    Note

    可以使用有表头或者无表头的CSV文件。

  2. 获取CSV文件存储路径。

步骤 3：修改配置文件

编译Exchange后，复制target/classes/application.conf文件设置相关配置。在本示例中，复制的文件名为sst_application.conf。各个配置项的详细说明请参见配置说明。

  1. {
  2.   # Spark相关配置
  3.   spark: {
  4.     app: {
  5.       name: Nebula Exchange 2.0
  6.     }
  8.     master:local
  10.     driver: {
  11.       cores: 1
  12.       maxResultSize: 1G
  13.     }
  15.     executor: {
  16.         memory:1G
  17.     }
  19.     cores:{
  20.       max: 16
  21.     }
  22.   }
  24.   # Nebula Graph相关配置
  25.   nebula: {
  26.     address:{
  27.       graph:["127.0.0.1:9669"]
  28.       meta:["127.0.0.1:9559"]
  29.     }
  30.     user: root
  31.     pswd: nebula
  32.     space: basketballplayer
  34.     # SST文件相关配置
  35.     path:{
  36.         # 本地临时存放生成的SST文件的目录
  37.         local:"/tmp"
  39.         # SST文件在HDFS的存储路径
  40.         remote:"/sst"
  42.         # HDFS的NameNode地址
  43.         hdfs.namenode: "hdfs://*.*.*.*:9000"
  44.     }
  46.     # 客户端连接参数
  47.     connection {
  48.       # socket连接、执行的超时时间，单位：毫秒。
  49.       timeout: 30000
  50.     }
  52.     error: {
  53.       # 最大失败数，超过后会退出应用程序。
  54.       max: 32
  55.       # 失败的导入作业将记录在输出路径中。
  56.       output: /tmp/errors
  57.     }
  59.     # 使用谷歌的RateLimiter来限制发送到NebulaGraph的请求。
  60.     rate: {
  61.       # RateLimiter的稳定吞吐量。
  62.       limit: 1024
  64.       # 从RateLimiter获取允许的超时时间，单位：毫秒
  65.       timeout: 1000
  66.     }
  67.   }
  70.   # 处理点
  71.   tags: [
  72.     # 设置Tag player相关信息。
  73.     {
  74.       # 指定Nebula Graph中定义的Tag名称。
  75.       name: player
  76.       type: {
  77.         # 指定数据源，使用CSV。
  78.         source: csv
  80.         # 指定如何将点数据导入Nebula Graph：Client或SST。
  81.         sink: sst
  82.       }
  84.       # 指定CSV文件的路径。
  85.       # 文件存储在HDFS上，用双引号括起路径，以hdfs://开头，例如"hdfs://ip:port/xx/xx"。
  86.       path: "hdfs://*.*.*.*:9000/dataset/vertex_player.csv"
  88.       # 如果CSV文件没有表头，使用[_c0, _c1, _c2, ..., _cn]表示其表头，并将列指示为属性值的源。
  89.       # 如果CSV文件有表头，则使用实际的列名。
  90.       fields: [_c1, _c2]
  92.       # 指定Nebula Graph中定义的属性名称。
  93.       # fields与nebula.fields的顺序必须一一对应。
  94.       nebula.fields: [age, name]
  96.       # 指定一个列作为VID的源。
  97.       # vertex的值必须与上述fields或者csv.fields中的列名保持一致。
  98.       # 目前，Nebula Graph 2.5.1仅支持字符串或整数类型的VID。
  99.       vertex: {
  100.         field:_c0
  101.       }
  103.       # 指定的分隔符。默认值为英文逗号（,）。
  104.       separator: ","
  106.       # 如果CSV文件有表头，请将header设置为true。
  107.       # 如果CSV文件没有表头，请将header设置为false。默认值为false。
  108.       header: false
  110.       # 指定单批次写入Nebula Graph的最大点数量。
  111.       batch: 256
  113.       # 指定Spark分片数量。
  114.       partition: 32
  115.     }
  117.     # 设置Tag team相关信息。
  118.     {
  119.       # 指定Nebula Graph中定义的Tag名称。
  120.       name: team
  121.       type: {
  122.         # 指定数据源，使用CSV。
  123.         source: csv
  125.         # 指定如何将点数据导入Nebula Graph：Client或SST。
  126.         sink: sst
  127.       }
  129.       # 指定CSV文件的路径。
  130.       # 文件存储在HDFS上，用双引号括起路径，以hdfs://开头，例如"hdfs://ip:port/xx/xx"。
  131.       path: "hdfs://*.*.*.*:9000/dataset/vertex_team.csv"
  133.       # 如果CSV文件没有表头，使用[_c0, _c1, _c2, ..., _cn]表示其表头，并将列指示为属性值的源。
  134.       # 如果CSV文件有表头，则使用实际的列名。
  135.       fields: [_c1]
  137.       # 指定Nebula Graph中定义的属性名称。
  138.       # fields与nebula.fields的顺序必须一一对应。
  139.       nebula.fields: [name]
  141.       # 指定一个列作为VID的源。
  142.       # vertex的值必须与上述fields或者csv.fields中的列名保持一致。
  143.       # 目前，Nebula Graph 2.5.1仅支持字符串或整数类型的VID。
  144.       vertex: {
  145.         field:_c0
  146.       }
  148.       # 指定的分隔符。默认值为英文逗号（,）。
  149.       separator: ","
  151.       # 如果CSV文件有表头，请将header设置为true。
  152.       # 如果CSV文件没有表头，请将header设置为false。默认值为false。
  153.       header: false
  155.       # 指定单批次写入Nebula Graph的最大点数量。
  156.       batch: 256
  158.       # 指定Spark分片数量。
  159.       partition: 32
  160.     }
  163.     # 如果需要添加更多点，请参考前面的配置进行添加。
  164.   ]
  165.   # 处理边
  166.   edges: [
  167.     # 设置Edge type follow相关信息。
  168.     {
  169.       # 指定Nebula Graph中定义的Edge type名称。
  170.       name: follow
  171.       type: {
  172.         # 指定数据源，使用CSV。
  173.         source: csv
  175.         # 指定如何将点数据导入Nebula Graph：Client或SST。
  176.         sink: sst
  177.       }
  179.       # 指定CSV文件的路径。
  180.       # 文件存储在HDFS上，用双引号括起路径，以hdfs://开头，例如"hdfs://ip:port/xx/xx"。
  181.       path: "hdfs://*.*.*.*:9000/dataset/edge_follow.csv"
  183.       # 如果CSV文件没有表头，使用[_c0, _c1, _c2, ..., _cn]表示其表头，并将列指示为属性值的源。
  184.       # 如果CSV文件有表头，则使用实际的列名。
  185.       fields: [_c2]
  187.       # 指定Nebula Graph中定义的属性名称。
  188.       # fields与nebula.fields的顺序必须一一对应。
  189.       nebula.fields: [degree]
  191.       # 指定一个列作为起始点和目的点的源。
  192.       # vertex的值必须与上述fields或者csv.fields中的列名保持一致。
  193.       # 目前，Nebula Graph 2.5.1仅支持字符串或整数类型的VID。
  194.       source: {
  195.         field: _c0
  196.       }
  197.       target: {
  198.         field: _c1
  199.       }
  201.       # 指定的分隔符。默认值为英文逗号（,）。
  202.       separator: ","
  204.       # 指定一个列作为rank的源(可选)。
  206.       #ranking: rank
  208.       # 如果CSV文件有表头，请将header设置为true。
  209.       # 如果CSV文件没有表头，请将header设置为false。默认值为false。
  210.       header: false
  212.       # 指定单批次写入Nebula Graph的最大边数量。
  213.       batch: 256
  215.       # 指定Spark分片数量。
  216.       partition: 32
  217.     }
  219.     # 设置Edge type serve相关信息。
  220.     {
  221.       # 指定Nebula Graph中定义的Edge type名称。
  222.       name: serve
  223.       type: {
  224.         # 指定数据源，使用CSV。
  225.         source: csv
  227.         # 指定如何将点数据导入Nebula Graph：Client或SST。
  228.         sink: sst
  229.       }
  231.       # 指定CSV文件的路径。
  232.       # 文件存储在HDFS上，用双引号括起路径，以hdfs://开头，例如"hdfs://ip:port/xx/xx"。
  233.       path: "hdfs://*.*.*.*:9000/dataset/edge_serve.csv"
  235.       # 如果CSV文件没有表头，使用[_c0, _c1, _c2, ..., _cn]表示其表头，并将列指示为属性值的源。
  236.       # 如果CSV文件有表头，则使用实际的列名。
  237.       fields: [_c2,_c3]
  239.       # 指定Nebula Graph中定义的属性名称。
  240.       # fields与nebula.fields的顺序必须一一对应。
  241.       nebula.fields: [start_year, end_year]
  243.       # 指定一个列作为起始点和目的点的源。
  244.       # vertex的值必须与上述fields或者csv.fields中的列名保持一致。
  245.       # 目前，Nebula Graph 2.5.1仅支持字符串或整数类型的VID。
  246.       source: {
  247.         field: _c0
  248.       }
  249.       target: {
  250.         field: _c1
  251.       }
  253.       # 指定的分隔符。默认值为英文逗号（,）。
  254.       separator: ","
  256.       # 指定一个列作为rank的源(可选)。
  257.       #ranking: _c5
  259.       # 如果CSV文件有表头，请将header设置为true。
  260.       # 如果CSV文件没有表头，请将header设置为false。默认值为false。
  261.       header: false
  263.       # 指定单批次写入Nebula Graph的最大边数量。
  264.       batch: 256
  266.       # 指定Spark分片数量。
  267.       partition: 32
  268.     }
  270.   ]
  271.   # 如果需要添加更多边，请参考前面的配置进行添加。
  272. }

步骤 4：生成SST文件

运行如下命令将CSV源文件生成为SST文件。关于参数的说明，请参见命令参数。

  1. ${SPARK_HOME}/bin/spark-submit --master "local" --class com.vesoft.nebula.exchange.Exchange <nebula-exchange-2.5.1.jar_path> -c <sst_application.conf_path>

Note

JAR包有两种获取方式：自行编译或者从maven仓库下载。

示例：

  1. ${SPARK_HOME}/bin/spark-submit  --master "local" --class com.vesoft.nebula.exchange.Exchange  /root/nebula-spark-utils/nebula-exchange/target/nebula-exchange-2.5.1.jar  -c /root/nebula-spark-utils/nebula-exchange/target/classes/sst_application.conf

任务执行完成后，可以在HDFS上的/sst目录（nebula.path.remote参数指定）内查看到生成的SST文件。

Note

如果对Schema有修改操作，例如重建图空间、修改Tag、修改Edge type等，需要重新生成SST文件，因为SST文件会验证Space ID、Tag ID、Edge ID等信息。

步骤 5：导入SST文件

Note

导入前请确认以下信息：

  • 确认所有部署Storage服务的机器上都已部署Hadoop服务，并配置HADOOP_HOME和JAVA_HOME。

  • Meta服务配置文件中的--ws_storage_http_port（如果没有，请手动添加）和Storage服务配置文件中的--ws_http_port一致。例如都为19779。

  • Graph服务配置文件中的--ws_meta_http_port（如果没有，请手动添加）和Meta服务配置文件中的--ws_http_port一致。例如都为19559。

Caution

如果需要导入SST文件至Nebula Graph 2.5.x中，请在Storage配置文件中添加--enable_vertex_cache =false，并重启Storage服务，才能正常导入SST文件，否则可能会出现没有覆盖旧数据的问题。导入后可以删除--enable_vertex_cache =false，该参数用于加速查询。

使用客户端工具连接Nebula Graph数据库，按如下操作导入SST文件：

  1. 执行命令选择之前创建的图空间。

    1. nebula> USE basketballplayer;

  2. 执行命令下载SST文件：

    1. nebula> DOWNLOAD HDFS "hdfs://<hadoop_address>:<hadoop_port>/<sst_file_path>";

    示例：

    1. nebula> DOWNLOAD HDFS "hdfs://*.*.*.*:9000/sst";

  3. 执行命令导入SST文件：

    1. nebula> INGEST;

Note

  • 如果需要重新下载，请在Nebula Graph安装路径内的data/storage/nebula目录内，将对应Space ID目录内的download文件夹删除，然后重新下载SST文件。如果是图空间是多副本，保存副本的所有机器都需要删除download文件夹。

  • 如果导入时出现问题需要重新导入，重新执行INGEST;即可。

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

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

  1. GO FROM "player100" OVER follow;

用户也可以使用命令SHOW STATS查看统计数据。

步骤 7：（如有）在Nebula Graph中重建索引

导入数据后，用户可以在Nebula Graph中重新创建并重建索引。详情请参见索引介绍。

最后更新: October 19, 2021