导入SST文件数据Graph

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

注意事项Graph

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

• 不支持属性的Default值。

背景信息Graph

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

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

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

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

适用场景Graph

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

  Caution

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

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

实现方法Graph

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

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

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

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

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

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

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

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

数据集Graph

本文以Graph为例。

环境配置Graph

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

• 硬件规格：
  • CPU：1.7 GHz Quad-Core Intel Core i7
  • 内存：16 GB

• Spark：2.4.7 单机版

• Hadoop：2.9.2 伪分布式部署

• NebulaGraph：2.5.1。

前提条件Graph

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

• 已经Graph并获取如下信息：

  • Graph服务和Meta服务的的IP地址和端口。
  • 拥有NebulaGraph写权限的用户名和密码。
  • Meta服务配置文件中的--ws_storage_http_port和Storage服务配置文件中的--ws_http_port一致。例如都为19779。
  • Graph服务配置文件中的--ws_meta_http_port和Meta服务配置文件中的--ws_http_port一致。例如都为19559。
  • Schema的信息，包括Tag和Edge type的名称、属性等。

• 已经Graph编译完成的.jar文件。本示例中使用Exchange 2.5.1。

• 已经安装Spark。

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

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

  Note

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

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

操作步骤Graph

步骤 1：在NebulaGraph中创建SchemaGraph

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

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

   要素	名称	属性
   Tag	player	name string, age int
   Tag	team	name string
   Edge Type	follow	degree int
   Edge Type	serve	start_year int, end_year int

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

   ## 创建图空间
   nebula> CREATE SPACE basketballplayer \
           (partition_num = 10, \
           replica_factor = 1, \
           vid_type = FIXED_STRING(30));
   
   ## 选择图空间basketballplayer
   nebula> USE basketballplayer;
   
   ## 创建Tag player
   nebula> CREATE TAG player(name string, age int);
   
   ## 创建Tag team
   nebula> CREATE TAG team(name string);
   
   ## 创建Edge type follow
   nebula> CREATE EDGE follow(degree int);
   
   ## 创建Edge type serve
   nebula> CREATE EDGE serve(start_year int, end_year int);
   

更多信息，请参见Graph。

步骤 2：处理CSV文件Graph

确认以下信息：

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

   Note

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

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

步骤 3：修改配置文件Graph

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

{
  # Spark相关配置
  spark: {
    app: {
      name: Nebula Exchange 2.0
    }

    master:local

    driver: {
      cores: 1
      maxResultSize: 1G
    }

    executor: {
        memory:1G
    }

    cores:{
      max: 16
    }
  }

  # NebulaGraph相关配置
  nebula: {
    address:{
      graph:["127.0.0.1:9669"]
      meta:["127.0.0.1:9559"]
    }
    user: root
    pswd: nebula
    space: basketballplayer

    # SST文件相关配置
    path:{
        # 本地临时存放生成的SST文件的目录
        local:"/tmp"

        # SST文件在HDFS的存储路径
        remote:"/sst"

        # HDFS的NameNode地址
        hdfs.namenode: "hdfs://*.*.*.*:9000"
    }

    # 客户端连接参数
    connection {
      # socket连接、执行的超时时间，单位：毫秒。
      timeout: 30000
    }

    error: {
      # 最大失败数，超过后会退出应用程序。
      max: 32
      # 失败的导入作业将记录在输出路径中。
      output: /tmp/errors
    }

    # 使用谷歌的RateLimiter来限制发送到NebulaGraph的请求。
    rate: {
      # RateLimiter的稳定吞吐量。
      limit: 1024

      # 从RateLimiter获取允许的超时时间，单位：毫秒
      timeout: 1000
    }
  }


  # 处理点
  tags: [
    # 设置Tag player相关信息。
    {
      # 指定NebulaGraph中定义的Tag名称。
      name: player
      type: {
        # 指定数据源，使用CSV。
        source: csv

        # 指定如何将点数据导入NebulaGraph：Client或SST。
        sink: sst
      }

      # 指定CSV文件的路径。
      # 文件存储在HDFS上，用双引号括起路径，以hdfs://开头，例如"hdfs://ip:port/xx/xx"。
      path: "hdfs://*.*.*.*:9000/dataset/vertex_player.csv"

      # 如果CSV文件没有表头，使用[_c0, _c1, _c2, ..., _cn]表示其表头，并将列指示为属性值的源。
      # 如果CSV文件有表头，则使用实际的列名。
      fields: [_c1, _c2]

      # 指定NebulaGraph中定义的属性名称。
      # fields与nebula.fields的顺序必须一一对应。
      nebula.fields: [age, name]

      # 指定一个列作为VID的源。
      # vertex的值必须与上述fields或者csv.fields中的列名保持一致。
      # 目前，NebulaGraph 2.5.1仅支持字符串或整数类型的VID。
      vertex: {
        field:_c0
      }

      # 指定的分隔符。默认值为英文逗号（,）。
      separator: ","

      # 如果CSV文件有表头，请将header设置为true。
      # 如果CSV文件没有表头，请将header设置为false。默认值为false。
      header: false

      # 指定单批次写入NebulaGraph的最大点数量。
      batch: 256

      # 指定Spark分片数量。
      partition: 32
    }

    # 设置Tag team相关信息。
    {
      # 指定NebulaGraph中定义的Tag名称。
      name: team
      type: {
        # 指定数据源，使用CSV。
        source: csv

        # 指定如何将点数据导入NebulaGraph：Client或SST。
        sink: sst
      }

      # 指定CSV文件的路径。
      # 文件存储在HDFS上，用双引号括起路径，以hdfs://开头，例如"hdfs://ip:port/xx/xx"。
      path: "hdfs://*.*.*.*:9000/dataset/vertex_team.csv"

      # 如果CSV文件没有表头，使用[_c0, _c1, _c2, ..., _cn]表示其表头，并将列指示为属性值的源。
      # 如果CSV文件有表头，则使用实际的列名。
      fields: [_c1]

      # 指定NebulaGraph中定义的属性名称。
      # fields与nebula.fields的顺序必须一一对应。
      nebula.fields: [name]

      # 指定一个列作为VID的源。
      # vertex的值必须与上述fields或者csv.fields中的列名保持一致。
      # 目前，NebulaGraph 2.5.1仅支持字符串或整数类型的VID。
      vertex: {
        field:_c0
      }

      # 指定的分隔符。默认值为英文逗号（,）。
      separator: ","

      # 如果CSV文件有表头，请将header设置为true。
      # 如果CSV文件没有表头，请将header设置为false。默认值为false。
      header: false

      # 指定单批次写入NebulaGraph的最大点数量。
      batch: 256

      # 指定Spark分片数量。
      partition: 32
    }


    # 如果需要添加更多点，请参考前面的配置进行添加。
  ]
  # 处理边
  edges: [
    # 设置Edge type follow相关信息。
    {
      # 指定NebulaGraph中定义的Edge type名称。
      name: follow
      type: {
        # 指定数据源，使用CSV。
        source: csv

        # 指定如何将点数据导入NebulaGraph：Client或SST。
        sink: sst
      }

      # 指定CSV文件的路径。
      # 文件存储在HDFS上，用双引号括起路径，以hdfs://开头，例如"hdfs://ip:port/xx/xx"。
      path: "hdfs://*.*.*.*:9000/dataset/edge_follow.csv"

      # 如果CSV文件没有表头，使用[_c0, _c1, _c2, ..., _cn]表示其表头，并将列指示为属性值的源。
      # 如果CSV文件有表头，则使用实际的列名。
      fields: [_c2]

      # 指定NebulaGraph中定义的属性名称。
      # fields与nebula.fields的顺序必须一一对应。
      nebula.fields: [degree]

      # 指定一个列作为起始点和目的点的源。
      # vertex的值必须与上述fields或者csv.fields中的列名保持一致。
      # 目前，NebulaGraph 2.5.1仅支持字符串或整数类型的VID。
      source: {
        field: _c0
      }
      target: {
        field: _c1
      }

      # 指定的分隔符。默认值为英文逗号（,）。
      separator: ","

      # 指定一个列作为rank的源(可选)。

      #ranking: rank

      # 如果CSV文件有表头，请将header设置为true。
      # 如果CSV文件没有表头，请将header设置为false。默认值为false。
      header: false

      # 指定单批次写入NebulaGraph的最大边数量。
      batch: 256

      # 指定Spark分片数量。
      partition: 32
    }

    # 设置Edge type serve相关信息。
    {
      # 指定NebulaGraph中定义的Edge type名称。
      name: serve
      type: {
        # 指定数据源，使用CSV。
        source: csv

        # 指定如何将点数据导入NebulaGraph：Client或SST。
        sink: sst
      }

      # 指定CSV文件的路径。
      # 文件存储在HDFS上，用双引号括起路径，以hdfs://开头，例如"hdfs://ip:port/xx/xx"。
      path: "hdfs://*.*.*.*:9000/dataset/edge_serve.csv"

      # 如果CSV文件没有表头，使用[_c0, _c1, _c2, ..., _cn]表示其表头，并将列指示为属性值的源。
      # 如果CSV文件有表头，则使用实际的列名。
      fields: [_c2,_c3]

      # 指定NebulaGraph中定义的属性名称。
      # fields与nebula.fields的顺序必须一一对应。
      nebula.fields: [start_year, end_year]

      # 指定一个列作为起始点和目的点的源。
      # vertex的值必须与上述fields或者csv.fields中的列名保持一致。
      # 目前，NebulaGraph 2.5.1仅支持字符串或整数类型的VID。
      source: {
        field: _c0
      }
      target: {
        field: _c1
      }

      # 指定的分隔符。默认值为英文逗号（,）。
      separator: ","

      # 指定一个列作为rank的源(可选)。
      #ranking: _c5

      # 如果CSV文件有表头，请将header设置为true。
      # 如果CSV文件没有表头，请将header设置为false。默认值为false。
      header: false

      # 指定单批次写入NebulaGraph的最大边数量。
      batch: 256

      # 指定Spark分片数量。
      partition: 32
    }

  ]
  # 如果需要添加更多边，请参考前面的配置进行添加。
}

步骤 4：生成SST文件Graph

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

${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包有两种获取方式：Graph或者从maven仓库下载。

示例：

${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文件Graph

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文件至NebulaGraph 2.5.x中，请在Graph中添加--enable_vertex_cache =false，并重启Storage服务，才能正常导入SST文件，否则可能会出现没有覆盖旧数据的问题。导入后可以删除--enable_vertex_cache =false，该参数用于加速查询。

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

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

   nebula> USE basketballplayer;
   

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

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

   示例：

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

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

   nebula> INGEST;
   

Note

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

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

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

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

GO FROM "player100" OVER follow;

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

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

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

---

最后更新: October 19, 2021