![Neo4j 資料匯入實現](https://www-cdn.nebula-graph.com.cn/nebula-blog/import-data-from-neo4j-to-nebula-graph.png)

本文主要講述如何使用資料匯入工具 Nebula Graph Exchange 將資料從 Neo4j 匯入到 [Nebula Graph](https://0x7.me/dineo4j2github) Database。在講述如何實操資料匯入之前，我們先來了解下 Nebula Graph 內部是如何實現這個匯入功能的。

## Nebula Graph Exchange 的資料處理原理

我們這個匯入工具名字是 Nebula Graph [Exchange](https://github.com/vesoft-inc/nebula-java/tree/master/tools/exchange)，採用 Spark 作為匯入平臺，來支援海量資料的匯入和保障效能。Spark 本身提供了不錯的抽象——DataFrame，使得可以輕鬆支援多種資料來源。在 DataFrame 的支援下，新增新的資料來源只需提供配置檔案讀取的程式碼和返回 DataFrame 的 Reader 類，即可支援新的資料來源。

![DataFrame](https://www-cdn.nebula-graph.com.cn/nebula-blog/dataframe-in-spark.png)

DataFrame 可以視為一種分散式存表格。DataFrame 可以儲存在多個節點的不同分割槽中，多個分割槽可以儲存在不同的機器上，從而支援並行操作。Spark 還提供了一套簡潔的 API 使使用者輕鬆操作 DataFrame 如同操作本地資料集一般。現在大多數資料庫提供直接將資料匯出成 DataFrame 功能，即使某個資料庫並未提供此功能也可以透過資料庫 driver 手動構建 DataFrame。

Nebula Graph Exchange 將資料來源的資料處理成 DataFrame 之後，會遍歷它的每一行，根據配置檔案中 fields 的對映關係，按列名獲取對應的值。在遍歷 `batchSize` 個行之後，Exchange 會將獲取的資料一次性寫入到 Nebula Graph 中。目前，Exchange 是透過生成 nGQL 語句再由 Nebula Client 非同步寫入資料，下一步會支援直接匯出 Nebula Graph 底層儲存的 sst 檔案，以獲取更好的效能。接下來介紹一下 Neo4j 資料來源匯入的具體實現。

## Neo4j 資料匯入具體實現

雖然 Neo4j 官方提供了可將資料直接匯出為 DataFrame 的庫，但使用它讀取資料難以滿足斷點續傳的需求，我們未直接使用這個庫，而是使用 Neo4j 官方的 driver 實現資料讀取。Exchange 透過在不同分割槽調取 Neo4j driver 執行不同 `skip` 和 `limit` 的 Cypher 語句，將資料分佈在不同的分割槽，來獲取更好的效能。這個分割槽數量由配置項 `partition` 指定。

Exchange 中的 Neo4jReader 類會先將使用者配置中的 `exec` Cypher 語句，`return` 後邊的語句替換成 `count(*)` 執行獲取資料總量，再根據分割槽數計算每個分割槽的起始偏移量和大小。這裡如果使用者配置了 `check_point_path` 目錄，會讀取目錄中的檔案，如果處於續傳的狀態，Exchange 會計算出每個分割槽應該的偏移量和大小。然後每個分割槽在 Cypher 語句後邊新增不同的 `skip` 和 `limit`，呼叫 driver 執行。最後將返回的資料處理成 DataFrame 就完成了 Neo4j 的資料匯入。

過程如下圖所示：

![資料匯入過程](https://www-cdn.nebula-graph.com.cn/nebula-blog/import-neo4j-to-dataframe.png)

## Neo4j 資料匯入實踐

我們這裡匯入演示的系統環境如下：

- cpu name：Intel(R) Xeon(R) CPU E5-2697 v3 @ 2.60GHz
- cpu cores：14
- memory size：251G

軟體環境如下：

- Neo4j：3.5.20 社群版
- Nebula graph：docker-compose 部署，預設配置
- Spark：單機版，版本為 2.4.6 pre-build for hadoop2.7

由於 Nebula Graph 是強 schema 資料庫，資料匯入前需先進行建立 Space，建 Tag 和 Edge 的 schema，具體的語法可以參考[這裡](https://docs.nebula-graph.com.cn/manual-CN/2.query-language/4.statement-syntax/1.data-definition-statements/create-space-syntax/)。

這裡建了名為 test 的 Space，副本數為 1。這裡建立了兩種 Tag 分別為 tagA 和 tagB，均含有 4 個屬性的點型別，此外，還建立一種名為 edgeAB 的邊型別，同樣含有 4 個屬性。具體的 nGQL 語句如下所示：

```sql
# 建立圖空間
CREATE SPACE test(replica_factor=1);
# 選擇圖空間 test
USE test;
# 建立標籤 tagA
CREATE TAG tagA(idInt int, idString string, tboolean bool, tdouble double);
# 建立標籤 tagB
CREATE TAG tagB(idInt int, idString string, tboolean bool, tdouble double);
# 建立邊型別 edgeAB
CREATE EDGE edgeAB(idInt int, idString string, tboolean bool, tdouble double);
```

同時向 Neo4j 匯入 Mock 資料——標籤為 tagA 和 tagB 的點，數量總共為 100 萬，並且匯入了連線 tagA 和 tagB 型別點邊型別為 edgeAB 的邊，共 1000 萬個。另外需要注意的是，從 Neo4j 匯出的資料在 Nebula Graph 中必須存在屬性，且資料對應的型別要同 Nebula Graph 一致。

最後為了提升向 Neo4j 匯入 Mock 資料的效率和 Mock 資料在 Neo4j 中的讀取效率，這裡為 tagA 和 tagB 的 `idInt` 屬性建了索引。關於索引需要注意 Exchange 並不會將 Neo4j 中的索引、約束等資訊匯入到 Nebula Graph 中，所以需要使用者在執行資料寫入在 Nebula Graph 之後，自行[建立索引](https://docs.nebula-graph.com.cn/manual-CN/2.query-language/4.statement-syntax/1.data-definition-statements/#_2)和 [REBUILD 索引](https://docs.nebula-graph.com.cn/manual-CN/2.query-language/4.statement-syntax/1.data-definition-statements/#_7)（為已有資料建立索引）。

接下來就可以將 Neo4j 資料匯入到 Nebula Graph 中了，首先我們需要下載和編譯打包專案，專案在 [nebula-java](https://github.com/vesoft-inc/nebula-java) 這個倉庫下 tools/exchange 資料夾中。可執行如下命令：

```shell
git clone https://github.com/vesoft-inc/nebula-java.git
cd nebula-java/tools/exchange
mvn package -DskipTests
```

然後就可以看到 `target/exchange-1.0.1.jar` 這個檔案。

接下來編寫配置檔案，配置檔案的格式為：HOCON（Human-Optimized Config Object Notation），可以基於 `src/main/resources/server_application.conf` 檔案的基礎上進行更改。首先對 nebula 配置項下的 address、user、pswd 和 space 進行配置，測試環境均為預設配置，所以這裡不需要額外的修改。然後進行 tags 配置，需要 tagA 和 tagB 的配置，這裡僅展示 tagA 配置，tagB 和 tagA 配置相同。

```shell
{
    # ======neo4j連線設定=======
    name: tagA
    # 必須和 Nebula Graph 的中 tag 名字一致，需要在 Nebula Graph 中事先建好 tag
    server: "bolt://127.0.0.1:7687"
    # neo4j 的地址配置
    user: neo4j
    # neo4j 的使用者名稱
    password: neo4j
    # neo4j 的密碼

encryption: false
    # (可選): 傳輸是否加密，預設值為 false
    database: graph.db
    # (可選): neo4j database 名稱，社群版不支援

# ======匯入設定============
    type: {
        source: neo4j
        # 還支援 PARQUET、ORC、JSON、CSV、HIVE、MYSQL、PULSAR、KAFKA...
        sink: client
        # 寫入 Nebula Graph 的方式，目前僅支援 client，未來會支援直接匯出 Nebula Graph 底層資料庫檔案
    }

nebula.fields: [idInt, idString, tdouble, tboolean]
    fields       : [idInt, idString, tdouble, tboolean]
    # 對映關係 fields，上方為 nebula 的屬性名，下方為 neo4j 的屬性名，一一對應
    # 對映關係的配置是 List 而不是 Map，是為了保持 fields 的順序，未來直接匯出 nebula 底層儲存檔案時需要

vertex: idInt
    # 作為 nebula vid 的 neo4j field，型別需要是整數(long or int)。

partition: 10
    # 分割槽數
    batch: 2000
    # 一次寫入 nebula 多少資料

check_point_path: "file:///tmp/test"
    # (可選): 儲存匯入進度資訊的目錄，用於斷點續傳

exec: "match (n:tagA) return n.idInt as idInt, n.idString as idString, n.tdouble as tdouble, n.tboolean as tboolean order by n.idInt"
}
```

邊的設定大部分與點的設定無異，但由於邊在 Nebula Graph 中有起點的 vid 和終點的 vid 標識，所以這裡需要指定作為邊起點 vid 的域和作為邊終點 vid 的域。

下面給出邊的特別配置。

```shell
source: {
  field: a.idInt
  # policy: "hash"
}
# 起點的 vid 設定
target: {
  field: b.idInt
  # policy: "uuid"
}
# 終點的 vid 設定

ranking: idInt
# (可選): 作為 rank 的 field

partition: 1
# 這裡分割槽數設定為 1，原因在後邊

exec: "match (a:tagA)-[r:edgeAB]->(b:tagB) return a.idInt, b.idInt, r.idInt as idInt, r.idString as idString, r.tdouble as tdouble, r.tboolean as tboolean order by id(r)"
```

點的 vertex 和邊的 source、target 配置項下都可以設定 policy hash/uuid，它可以將型別為字串的域作為點的 vid，透過 hash/uuid 函式將字串對映成整數。

上面的例子由於作為點的 vid 為整數，所以並不需要 policy 的設定。hash/uuid的 區別請看[這裡](https://docs.nebula-graph.com.cn/manual-CN/2.query-language/2.functions-and-operators/uuid/)。

[Cypher 標準](https://neo4j.com/docs/cypher-manual/3.5/clauses/skip/)中如果沒有 `order by` 約束的話就不能保證每次查詢結果的排序一致，雖然看起來即便不加 `order by` Neo4j 返回的結果順序也是不變的，但為了防止可能造成的匯入時資料丟失，還是強烈建議在 Cypher 語句中加入 `order by`，雖然這會增加匯入的時間。為了提升匯入效率， `order by` 語句最好選取有索引的屬性作為排序的屬性。如果沒有索引，也可觀察預設的排序，選擇合適的排序屬性以提高效率。如果預設的排序找不到規律，可以使用點/關係的 ID 作為排序屬性，並且將 `partition` 的值儘量設小，減少 Neo4j 的排序壓力，本文中邊 `edgeAB` 的 `partition` 就設定為 1。

另外 Nebula Graph 在建立點和邊時會將 ID 作為唯一主鍵，如果主鍵已存在則會覆蓋該主鍵中的資料。所以假如將某個 Neo4j 屬性值作為 Nebula Graph 的 ID，而這個屬性值在 Neo4j 中是有重複的，就會導致“重複 ID”對應的資料有且只有一條會存入 Nebula Graph 中，其它的則會被覆蓋掉。由於資料匯入過程是併發地往 Nebula Graph 中寫資料，最終儲存的資料並不能保證是 Neo4j 中最新的資料。

這裡還要留意下斷點續傳功能，在斷點和續傳之間，資料庫不應該改變狀態，如新增資料或刪除資料，且 `partition` 數量也不能更改，否則可能會有資料丟失。

最後由於 Exchange 需要在不同分割槽執行不同 `skip` 和 `limit` 的 Cypher 語句，所以使用者提供的 Cypher 語句不能含有 `skip` 和 `limit` 語句。

接下來就可以執行 Exchange 程式導資料了，執行如下命令：

```shell
$SPARK_HOME/bin/spark-submit  --class com.vesoft.nebula.tools.importer.Exchange --master "local[10]" target/exchange-1.0.1.jar -c /path/to/conf/neo4j_application.conf
```

在上述這些配置下，匯入 100 萬個點用時 13s，匯入 1000 萬條邊用時 213s，總用時是 226s。

## 附：Neo4j 3.5 Community 和 Nebula Graph 1.0.1的一些比較

Neo4j 和 Nebula Graph 在系統架構、資料模型和訪問方式上都有一些差異，下表列舉了常見的異同

![neo4j 和 nebula graph 比較](https://www-cdn.nebula-graph.com.cn/nebula-blog/neo4j-vs-nebula-graph.png)

> 作者有話說：Hi，我是李夢捷，圖資料庫 Nebula Graph 的研發工程師，如果你對此文有疑問，歡迎來我們的 Nebula Graph 論壇交流下心得~~

喜歡這篇文章？來來來，給我們的 [GitHub](https://0x7.me/dineo4j2github) 點個 star 表鼓勵啦~~ ?‍♂️?‍♀️ [手動跪謝]

交流圖資料庫技術？交個朋友，Nebula Graph 官方小助手微信：[NebulaGraphbot](https://www-cdn.nebula-graph.com.cn/nebula-blog/nbot.png) 拉你進交流群~~

## 推薦閱讀

- [360 數科實踐：JanusGraph 到 NebulaGraph 遷移](https://nebula-graph.com.cn/posts/migrate-from-janusgraph-to-nebula-graph/)

從 Neo4j 匯入 Nebula Graph 實踐見 SPark 資料匯入原理

相關文章