> 本文首發於 **[Nebula Graph Community 公眾號](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/WeChatOffical.png)**

最近我試著搭建了方便大家一鍵試玩的 Nebula Graph 中的 [Spark](https://spark.apache.org/) 相關的專案，今天就把它們整理成文分享給大家。而且，我趟出來了 PySpark 下的 Nebula Spark Connector 的使用方式，後邊也會一併貢獻到文件裡。

## NebulaGraph 的三個 Spark 子專案

我曾經圍繞 NebulaGraph 的所有資料匯入方法畫過一個[草圖](https://www.siwei.io/sketches/nebula-data-import-options/)，其中已經包含了 Spark Connector，Nebula Exchange 的簡單介紹。在這篇文章中我將它們和另外的 Nebula Algorithm 進行稍微深入的探討。

> 注：[這篇文件](https://docs.nebula-graph.com.cn/3.1.0/20.appendix/write-tools/) 也很清楚為我們列舉了不同匯入工具的選擇。

TL;DR

- Nebula Spark Connector 是一個 Spark Lib，它能讓 Spark 應用程式能夠以 `dataframe` 的形式從 NebulaGraph 中讀取和寫入圖資料。 
- Nebula Exchange 建立在 Nebula Spark Connector 之上，作為一個 Spark Lib 同時可以直接被 Spark 提交 JAR 包執行的應用程式，它的設計目標是和 NebulaGraph 交換不同的資料來源（對於開源版本，它是單向的：寫入，而對於企業版本，它是雙向的）。Nebula Exchange 支援的很多不同型別的資料來源如：[MySQL](https://www.mysql.com/cn/)、[Neo4j](https://neo4j.com/)、[PostgreSQL](https://www.postgresql.org/)、[ClickHouse](https://clickhouse.com/)、[Hive](https://hive.apache.org/) 等。除了直接寫入 NebulaGraph，它還可以選擇生成 SST 檔案，並將其注入 NebulaGraph，以便使用 NebulaGraph 叢集之外算力幫助排序底層。
- Nebula Algorithm，建立在 Nebula Spark Connector 和 GraphX 之上，也是一個Spark Lib 和 Spark 上的應用程式，它用來在 NebulaGraph 的圖上執行常用的圖演算法（pagerank，LPA等）。

## Nebula Spark Connector

- 程式碼：https://github.com/vesoft-inc/nebula-spark-connector
- 文件：https://docs.nebula-graph.io/3.1.0/nebula-spark-connector/
- JAR 包：https://repo1.maven.org/maven2/com/vesoft/nebula-spark-connector/
- 程式碼例子：[example](https://github.com/vesoft-inc/nebula-spark-connector/tree/master/example)

### NebulaGraph Spark Reader

為了從 NebulaGraph 中讀取資料，比如讀 vertex，Nebula Spark Connector 將掃描所有帶有給定 TAG 的 Nebula StorageD，比如這樣表示掃描 `player` 這個 TAG ：`withLabel("player")`，我們還可以指定 vertex 的屬性：`withReturnCols(List("name", "age"))`。

指定好所有的讀 TAG 相關的配置之後，呼叫 `spark.read.nebula.loadVerticesToDF` 返回得到的就是掃描 NebulaGraph 之後轉換為 Dataframe 的圖資料，像這樣：

```scala
  def readVertex(spark: SparkSession): Unit = {
    LOG.info("start to read nebula vertices")
    val config =
      NebulaConnectionConfig
        .builder()
        .withMetaAddress("metad0:9559,metad1:9559,metad2:9559")
        .withConenctionRetry(2)
        .build()
    val nebulaReadVertexConfig: ReadNebulaConfig = ReadNebulaConfig
      .builder()
      .withSpace("basketballplayer")
      .withLabel("player")
      .withNoColumn(false)
      .withReturnCols(List("name", "age"))
      .withLimit(10)
      .withPartitionNum(10)
      .build()
    val vertex = spark.read.nebula(config, nebulaReadVertexConfig).loadVerticesToDF()
    vertex.printSchema()
    vertex.show(20)
    println("vertex count: " + vertex.count())
  }
```

寫入的例子我這裡不列出，不過，前邊給出的程式碼示例的連結裡是有更詳細的例子，這裡值得一提的是，**Spark Connector 讀資料為了滿足圖分析、圖計算的大量資料場景**，和大部分其他客戶端非常不同，它直接繞過了 GraphD，透過掃描 MetaD 和 StorageD 獲得資料，但是寫入的情況則是透過 GraphD 發起 nGQL DML 語句寫入的。

接下來我們來做一個上手練習吧。

### 上手 Nebula Spark Connector

先決條件：假設下面的程式是在一臺有網際網路連線的 Linux 機器上執行的，最好是預裝了 Docker 和 Docker-Compose。

#### 拉起環境

首先，讓我們用 [Nebula-Up](https://github.com/wey-gu/nebula-up/) 部署基於容器的 NebulaGraph Core v3、Nebula Studio、Nebula Console 和 Spark、Hadoop 環境，如果還沒安裝好它也會嘗試為我們安裝 Docker 和 Docker-Compose。

```bash
# Install Core with Spark Connector, Nebula Algorithm, Nebula Exchange
curl -fsSL nebula-up.siwei.io/all-in-one.sh | bash -s -- v3 spark
```

> 你知道嗎 [Nebula-UP](https://github.com/wey-gu/nebula-up/) 可以一鍵裝更多東西，如果你的環境配置大一點（比如 8 GB RAM）`curl -fsSL nebula-up.siwei.io/all-in-one.sh | bash` 可以裝更多東西，但是請注意 [Nebula-UP](https://github.com/wey-gu/nebula-up/) 不是為生產環境準備的。

上述邊指令碼執行後，讓我們用 [Nebula-Console](https://docs.nebula-graph.com.cn/3.1.0/nebula-console/)（Nebula Graph 的命令列客戶端）來連線它。

```bash
# Connect to nebula with console
~/.nebula-up/console.sh
# Execute any queryies like
~/.nebula-up/console.sh -e "SHOW HOSTS"
```

載入一份資料進去，並執行一個圖查詢：

```bash
# Load the sample dataset
~/.nebula-up/load-basketballplayer-dataset.sh
# 等一分鐘左右

# Make a Graph Query the sample dataset
~/.nebula-up/console.sh -e 'USE basketballplayer; FIND ALL PATH FROM "player100" TO "team204" OVER * WHERE follow.degree is EMPTY or follow.degree >=0 YIELD path AS p;'
```

#### 進入 Spark 環境

執行下面這一行，我們就可以進入到 Spark 環境：

```bash
docker exec -it spark_master_1 bash
```

如果我們想執行編譯，可以在裡邊安裝 `mvn`：

```bash
docker exec -it spark_master_1 bash
# in the container shell

export MAVEN_VERSION=3.5.4
export MAVEN_HOME=/usr/lib/mvn
export PATH=$MAVEN_HOME/bin:$PATH

wget http://archive.apache.org/dist/maven/maven-3/$MAVEN_VERSION/binaries/apache-maven-$MAVEN_VERSION-bin.tar.gz && \
  tar -zxvf apache-maven-$MAVEN_VERSION-bin.tar.gz && \
  rm apache-maven-$MAVEN_VERSION-bin.tar.gz && \
  mv apache-maven-$MAVEN_VERSION /usr/lib/mvn
```

#### 跑 Spark Connector 的例子

##### 選項 1（推薦）：透過 PySpark

- 進入 PySpark Shell

```bash
~/.nebula-up/nebula-pyspark.sh
```

- 呼叫 Nebula Spark Reader

```python
# call Nebula Spark Connector Reader
df = spark.read.format(
  "com.vesoft.nebula.connector.NebulaDataSource").option(
    "type", "vertex").option(
    "spaceName", "basketballplayer").option(
    "label", "player").option(
    "returnCols", "name,age").option(
    "metaAddress", "metad0:9559").option(
    "partitionNumber", 1).load()

# show the dataframe with limit of 2
df.show(n=2)
```

- 返回結果例子

```python
      ____              __
     / __/__  ___ _____/ /__
    _\ \/ _ \/ _ `/ __/  '_/
   /__ / .__/\_,_/_/ /_/\_\   version 2.4.5
      /_/

Using Python version 2.7.16 (default, Jan 14 2020 07:22:06)
SparkSession available as 'spark'.
>>> df = spark.read.format(
...   "com.vesoft.nebula.connector.NebulaDataSource").option(
...     "type", "vertex").option(
...     "spaceName", "basketballplayer").option(
...     "label", "player").option(
...     "returnCols", "name,age").option(
...     "metaAddress", "metad0:9559").option(
...     "partitionNumber", 1).load()
>>> df.show(n=2)
+---------+--------------+---+
|_vertexId|          name|age|
+---------+--------------+---+
|player105|   Danny Green| 31|
|player109|Tiago Splitter| 34|
+---------+--------------+---+
only showing top 2 rows
```

##### 選項 2：編譯、提交示例 JAR 包

- 先克隆 Spark Connector 和它示例程式碼的程式碼倉庫，然後編譯：

> 注意，我們使用了 master 分支，因為當下 master 分支是相容 3.x 的，一定要保證 spark connector 和資料庫核心版本是匹配的，版本對應關係參考程式碼倉庫的 `README.md` 。

```bash
cd ~/.nebula-up/nebula-up/spark
git clone https://github.com/vesoft-inc/nebula-spark-connector.git

docker exec -it spark_master_1 bash
cd /root/nebula-spark-connector
```

- 替換示例專案的程式碼

```bash
echo > example/src/main/scala/com/vesoft/nebula/examples/connector/NebulaSparkReaderExample.scala

vi example/src/main/scala/com/vesoft/nebula/examples/connector/NebulaSparkReaderExample.scala
```

- 把如下的程式碼貼上進去，這裡邊我們對前邊載入的圖： `basketballplayer` 上做了頂點和邊的讀操作：分別呼叫 `readVertex` 和 `readEdges`。

```scala
package com.vesoft.nebula.examples.connector

import com.facebook.thrift.protocol.TCompactProtocol
import com.vesoft.nebula.connector.connector.NebulaDataFrameReader
import com.vesoft.nebula.connector.{NebulaConnectionConfig, ReadNebulaConfig}
import org.apache.spark.SparkConf
import org.apache.spark.sql.SparkSession
import org.slf4j.LoggerFactory

object NebulaSparkReaderExample {

private val LOG = LoggerFactory.getLogger(this.getClass)

def main(args: Array[String]): Unit = {

val sparkConf = new SparkConf
    sparkConf
      .set("spark.serializer", "org.apache.spark.serializer.KryoSerializer")
      .registerKryoClasses(Array[Class[_]](classOf[TCompactProtocol]))
    val spark = SparkSession
      .builder()
      .master("local")
      .config(sparkConf)
      .getOrCreate()

readVertex(spark)
    readEdges(spark)

spark.close()
    sys.exit()
  }

def readVertex(spark: SparkSession): Unit = {
    LOG.info("start to read nebula vertices")
    val config =
      NebulaConnectionConfig
        .builder()
        .withMetaAddress("metad0:9559,metad1:9559,metad2:9559")
        .withConenctionRetry(2)
        .build()
    val nebulaReadVertexConfig: ReadNebulaConfig = ReadNebulaConfig
      .builder()
      .withSpace("basketballplayer")
      .withLabel("player")
      .withNoColumn(false)
      .withReturnCols(List("name", "age"))
      .withLimit(10)
      .withPartitionNum(10)
      .build()
    val vertex = spark.read.nebula(config, nebulaReadVertexConfig).loadVerticesToDF()
    vertex.printSchema()
    vertex.show(20)
    println("vertex count: " + vertex.count())
  }

def readEdges(spark: SparkSession): Unit = {
    LOG.info("start to read nebula edges")

val config =
      NebulaConnectionConfig
        .builder()
        .withMetaAddress("metad0:9559,metad1:9559,metad2:9559")
        .withTimeout(6000)
        .withConenctionRetry(2)
        .build()
    val nebulaReadEdgeConfig: ReadNebulaConfig = ReadNebulaConfig
      .builder()
      .withSpace("basketballplayer")
      .withLabel("follow")
      .withNoColumn(false)
      .withReturnCols(List("degree"))
      .withLimit(10)
      .withPartitionNum(10)
      .build()
    val edge = spark.read.nebula(config, nebulaReadEdgeConfig).loadEdgesToDF()
    edge.printSchema()
    edge.show(20)
    println("edge count: " + edge.count())
  }

}
```

- 然後打包成 JAR 包

```bash
/usr/lib/mvn/bin/mvn install -Dgpg.skip -Dmaven.javadoc.skip=true -Dmaven.test.skip=true
```

- 最後，把它提交到 Spark 裡執行：

```bash
cd example

/spark/bin/spark-submit --master "local" \
    --class com.vesoft.nebula.examples.connector.NebulaSparkReaderExample \
    --driver-memory 4g target/example-3.0-SNAPSHOT.jar

# 退出 spark 容器
exit
```

- 成功之後，我們會得到返回結果：

22/04/19 07:29:36 INFO DAGScheduler: Job 4 finished: show at NebulaSparkReaderExample.scala:82, took 0.135543 s
+---------+---------+-----+------+
|   _srcId|   _dstId|_rank|degree|
+---------+---------+-----+------+
|player105|player100|    0|    70|
|player105|player104|    0|    83|
|player105|player116|    0|    80|
|player109|player100|    0|    80|
|player109|player125|    0|    90|
|player118|player120|    0|    90|
|player118|player131|    0|    90|
|player143|player150|    0|    90|
|player114|player103|    0|    90|
|player114|player115|    0|    90|
|player114|player140|    0|    90|
|player150|player120|    0|    80|
|player150|player137|    0|    90|
|player150|player143|    0|    90|
|player103|player102|    0|    70|
|player113|player100|    0|    99|
|player113|player101|    0|    99|
|player113|player104|    0|    99|
|player113|player105|    0|    99|
|player113|player106|    0|    99|
+---------+---------+-----+------+
only showing top 20 rows
```

事實上，在這個程式碼倉庫下還有更多的例子，特別是 [GraphX](https://spark.apache.org/docs/latest/graphx-programming-guide.html) 的例子，你可以嘗試自己去探索這部分。

> 請注意，在 GraphX 假定頂點 ID 是數字型別的，因此對於字串型別的頂點 ID 情況，需要進行實時轉換，請參考 [Nebula Algorithom 中的例子](https://github.com/vesoft-inc/nebula-algorithm/blob/a82d7092d928a2f3abc45a727c24afb888ff8e4f/example/src/main/scala/com/vesoft/nebula/algorithm/PageRankExample.scala#L31)，瞭解如何繞過這一問題。

## Nebula Exchange

- 程式碼：https://github.com/vesoft-inc/nebula-exchange/
- 文件：https://docs.nebula-graph.com.cn/3.1.0/nebula-exchange/about-exchange/ex-ug-what-is-exchange/
- JAR 包：https://github.com/vesoft-inc/nebula-exchange/releases
- 配置例子： [exchange-common/src/test/resources/application.conf](https://github.com/vesoft-inc/nebula-exchange/blob/master/exchange-common/src/test/resources/application.conf)

Nebula Exchange 是一個 Spark Lib，也是一個可以直接提交執行的 Spark 應用，它被用來從多個資料來源讀取資料寫入 NebulaGraph 或者輸出 [Nebula Graph SST 檔案](https://docs.nebula-graph.com.cn/3.1.0/nebula-exchange/use-exchange/ex-ug-import-from-sst/#step_5_import_the_sst_file)。

![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/2f98d7887970432e9c457db33cc8e302~tplv-k3u1fbpfcp-zoom-1.image)

透過 spark-submit 的方式使用 Nebula Exchange 的方法很直接：

- 首先建立配置檔案，讓 Exchange 知道應該如何獲取和寫入資料
- 然後用指定的配置檔案呼叫 Exchange 包

現在，讓我們用上一章中建立的相同環境做一個實際測試。

### 一鍵試玩 Exchange

#### 先跑起來看看吧

> 請參考前邊[拉起環境](#拉起環境)這一章節，先一鍵裝好環境。

一鍵執行：

```
~/.nebula-up/nebula-exchange-example.sh
```

恭喜你，已經第一次執行成功一個 Exchange 的資料匯入任務啦！

#### 再看看一些細節

這個例子裡，我們實際上是用 Exchange 從 CSV 檔案這一其中支援的資料來源中讀取資料寫入 NebulaGraph 叢集的。這個 CSV 檔案中第一列是頂點 ID，第二和第三列是 "姓名 "和 "年齡 "的屬性：

```bash
player800,"Foo Bar",23
player801,"Another Name",21
```

- 我們們可以進到 Spark 環境裡看看

```bash
docker exec -it spark_master_1 bash
cd /root
```

- 可以看到我們提交 Exchange 任務時候指定的配置檔案 `exchange.conf` 它是一個 `HOCON` 格式的檔案：
  - 在 `.nebula` 中描述了 NebulaGraph 叢集的相關資訊
  - 在 `.tags` 中描述瞭如何將必填欄位對應到我們的資料來源（這裡是 CSV 檔案）等有關 Vertecies 的資訊。

```HOCON
{
  # Spark relation config
  spark: {
    app: {
      name: Nebula Exchange
    }

master:local

driver: {
      cores: 1
      maxResultSize: 1G
    }

executor: {
        memory: 1G
    }

cores:{
      max: 16
    }
  }

# Nebula Graph relation config
  nebula: {
    address:{
      graph:["graphd:9669"]
      meta:["metad0:9559", "metad1:9559", "metad2:9559"]
    }
    user: root
    pswd: nebula
    space: basketballplayer

# parameters for SST import, not required
    path:{
        local:"/tmp"
        remote:"/sst"
        hdfs.namenode: "hdfs://localhost:9000"
    }

# nebula client connection parameters
    connection {
      # socket connect & execute timeout, unit: millisecond
      timeout: 30000
    }

error: {
      # max number of failures, if the number of failures is bigger than max, then exit the application.
      max: 32
      # failed import job will be recorded in output path
      output: /tmp/errors
    }

# use google's RateLimiter to limit the requests send to NebulaGraph
    rate: {
      # the stable throughput of RateLimiter
      limit: 1024
      # Acquires a permit from RateLimiter, unit: MILLISECONDS
      # if it can't be obtained within the specified timeout, then give up the request.
      timeout: 1000
    }
  }

# Processing tags
  # There are tag config examples for different dataSources.
  tags: [

# HDFS csv
    # Import mode is client, just change type.sink to sst if you want to use client import mode.
    {
      name: player
      type: {
        source: csv
        sink: client
      }
      path: "file:///root/player.csv"
      # if your csv file has no header, then use _c0,_c1,_c2,.. to indicate fields
      fields: [_c1, _c2]
      nebula.fields: [name, age]
      vertex: {
        field:_c0
      }
      separator: ","
      header: false
      batch: 256
      partition: 32
    }

]
}
```

- 我們應該能看到那個 CSV 資料來源和這個配置檔案都在同一個目錄下了：

```bash
bash-5.0# ls -l
total 24
drwxrwxr-x    2 1000     1000          4096 Jun  1 04:26 download
-rw-rw-r--    1 1000     1000          1908 Jun  1 04:23 exchange.conf
-rw-rw-r--    1 1000     1000          2593 Jun  1 04:23 hadoop.env
drwxrwxr-x    7 1000     1000          4096 Jun  6 03:27 nebula-spark-connector
-rw-rw-r--    1 1000     1000            51 Jun  1 04:23 player.csv
```

-  然後，實際上我們可以手動再次提交一下這個 Exchange 任務

```bash
/spark/bin/spark-submit --master local \
    --class com.vesoft.nebula.exchange.Exchange download/nebula-exchange.jar \
    -c exchange.conf
```

- 部分返回結果

```log
22/06/06 03:56:26 INFO Exchange$: Processing Tag player
22/06/06 03:56:26 INFO Exchange$: field keys: _c1, _c2
22/06/06 03:56:26 INFO Exchange$: nebula keys: name, age
22/06/06 03:56:26 INFO Exchange$: Loading CSV files from file:///root/player.csv
...
22/06/06 03:56:41 INFO Exchange$: import for tag player cost time: 3.35 s
22/06/06 03:56:41 INFO Exchange$: Client-Import: batchSuccess.player: 2
22/06/06 03:56:41 INFO Exchange$: Client-Import: batchFailure.player: 0
...
```

更多的資料來源，請參考文件和配置的例子。

> 關於 Exchange 輸出 SST 檔案的實踐，你可以參考文件和我的舊文 [Nebula Exchange SST 2.x實踐指南](https://www.siwei.io/nebula-exchange-sst-2.x/)。

## Nebula Algorithm

- 程式碼倉庫： https://github.com/vesoft-inc/nebula-algorithm
- 文件：https://docs.nebula-graph.com.cn/3.1.0/nebula-algorithm/
- JAR 包：https://repo1.maven.org/maven2/com/vesoft/nebula-algorithm/
- 示例程式碼：[example/src/main/scala/com/vesoft/nebula/algorithm](example/src/main/scala/com/vesoft/nebula/algorithm)

### 透過 spark-submit 提交任務

> 我在[這個程式碼倉庫](https://github.com/wey-gu/nebula-livejournal)裡給出了例子，今天我們藉助 Nebula-UP 可以更方便體驗它。
>
> 參考前邊[拉起環境](#拉起環境)這一章節，先一鍵裝好環境。

在如上透過 Nebula-UP 的 Spark 模式部署了需要的依賴之後

- 載入 [LiveJournal](https://snap.stanford.edu/data/soc-LiveJournal1.html) 資料集

```bash
~/.nebula-up/load-LiveJournal-dataset.sh
```

- 在 LiveJournal 資料集上執行一個 PageRank 演算法，結果輸出到 CSV 檔案中

```bash
~/.nebula-up/nebula-algo-pagerank-example.sh
```

- 檢查輸出結果：

```bash
docker exec -it spark_master_1 bash

head /output/part*000.csv
_id,pagerank
637100,0.9268620883822242
108150,1.1855749056722755
957460,0.923720299211093
257320,0.9967932799358413
```

#### 配置檔案解讀

完整檔案在[這裡](https://github.com/wey-gu/nebula-livejournal/blob/main/nebula-algorithm/algo-pagerank.conf)，這裡，我們介紹一下主要的欄位：

- `.data` 指定了源是 Nebula，表示從叢集獲取圖資料，輸出`sink`是 `csv`，表示寫到本地檔案裡。

```hocon
  data: {
    # data source. optional of nebula,csv,json
    source: nebula
    # data sink, means the algorithm result will be write into this sink. optional of nebula,csv,text
    sink: csv
    # if your algorithm needs weight
    hasWeight: false
  }
```

- `.nebula.read` 規定了讀 NebulaGraph 叢集的對應關係，這裡是讀取所有 edge type: `follow` 的邊資料為一整張圖

```hocon
  nebula: {
    # algo's data source from Nebula. If data.source is nebula, then this nebula.read config can be valid.
    read: {
        # Nebula metad server address, multiple addresses are split by English comma
        metaAddress: "metad0:9559"
        # Nebula space
        space: livejournal
        # Nebula edge types, multiple labels means that data from multiple edges will union together
        labels: ["follow"]
        # Nebula edge property name for each edge type, this property will be as weight col for algorithm.
        # Make sure the weightCols are corresponding to labels.
        weightCols: []
    }
```

- `.algorithm` 裡配置了我們要呼叫的演算法，和演算法的配置

```hocon
  algorithm: {
    executeAlgo: pagerank

# PageRank parameter
    pagerank: {
        maxIter: 10
        resetProb: 0.15  # default 0.15
    }
```

### 作為一個庫在 Spark 中呼叫 Nebula Algoritm

請注意另一方面，我們可以將 Nebula Algoritm 作為一個庫呼叫，它的好處在於：

- 對演算法的輸出格式有更多的控制/定製功能

- 可以對非數字 ID 的情況進行轉換，見[這裡](https://github.com/vesoft-inc/nebula-algorithm/blob/a82d7092d928a2f3abc45a727c24afb888ff8e4f/example/src/main/scala/com/vesoft/nebula/algorithm/PageRankExample.scala#L48)

這裡我先不給出例子了，如果大家感興趣可以給 Nebula-UP 提需求，我也會增加相應的例子。

---

交流圖資料庫技術？加入 Nebula 交流群請先[填寫下你的 Nebula 名片](https://wj.qq.com/s2/8321168/8e2f/)，Nebula 小助手會拉你進群~~

一文了解 Nebula Graph 上的 Spark 專案

相關文章