*以下文章来源于浅谈架构 ，作者阿七*
![图数据库系统重构之路](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/20230927-01.png)

*“本文由社区用户 @阿七从第一视角讲述其团队重构图数据库的过程，首发于阿七公众号「浅谈架构」”*

读过我公众号文章的同学都知道，我做过很多次重构，可以说是“重构钉子户”，但是这次，重构图数据库 OrientDB 为 NebulaGraph [https://www.nebula-graph.com.cn/](https://www.nebula-graph.com.cn/)，可以说是我做过最艰难的一次重构。

而这篇文章就来聊聊，图数据库重构之路。

# Part 01. 难点在哪里

* **历史包袱重**，原来使用 OrientDB 系统是 2016 年开始开发的，逻辑很复杂，历史背景完全不清楚。
* **业务不了解**，我们是临时接的大数据需求，之前没有参与过这块业务，完全不了解。
* **技术栈不了解**，图数据库是第一次接触（团队中也没有人了解），OrientDB 和 NebulaGraph 之前都没有接触过，原来老系统大部分代码是 Scala 语言写的，系统中使用的 HBase、Spark、Kafka，对于我们也比较陌生。
* **时间紧迫**

总结来说: 业务不了解，技术栈不熟悉。

这里想和大家交流下：在业务和技术栈都不熟的情况下，如何做重构呢？

# Part 02. 技术方案

下面介绍一下本次重构技术方案

## 1. 迁移背景 WHY

**猎户座的图数据库 OrientDB 存在性能瓶颈和单点问题，需升级为 NebulaGraph。**

老系统使用技术栈无法支持弹性伸缩，监控报警设施也不够完善。

具体的使用痛点后续我将会写一篇文章具体讲述下，本篇就不详细展开了。

## 2. 调研事项 SEARCH

既然业务都不熟悉，那我们都调研了哪些东西呢？

* **对外接口梳理**：梳理系统所有对外接口，包括接口名、接口用途、请求量 QPS、平均耗时，调用方（服务和 IP）；
* **老系统核心流程梳理**：输出老系统整理架构图，重要的接口（大概 10 个）输出流程图；
* **环境梳理**：涉及到的需要改造的项目有哪些，应用部署、MySQL、Redis、HBase 集群 IP，及目前线上部署分支整理；
* **触发场景**：接口都是如何触发的，从业务使用场景出发，每个接口至少一个场景覆盖到，方便后期功能验证；
* **改造方案**：可行性分析，针对每一个接口，如何改造（OrientDB 语句改为 NebulaGraph 查询语句），入图（写流程）如何改造；
* **新系统设计方案**: 输出整理架构图，核心流程图。

## 3. 项目目标 TARGET

完成图数据库数据源 OrientDB 改造为 NebulaGraph，重构老系统统一技术栈为 Java，支持服务水平扩展。

## 4. 整体方案 SOLUTION

我们采用了比较激进的方案:

* 从调用接口入口出发，直接重写底层老系统，影响面可控；
* 一劳永逸，方便后期维护；
* 统一 Java 技术栈、接入公司统一服务框架，更利于监控及维护；
* 基础图数据库应用边界清晰，后续上层应用接入图数据库更简单。

注：这里就贴调研阶段画的图，图涉及业务，我这里就不列举了。

## 5. 灰度方案 A/B TEST

![图数据库 灰度方案](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/20230927-02.png)

### **灰度方案**

    
* 写请求：采用同步双写
* 读请求：按流量从小到大陆续迁移、平滑过渡

### **灰度计划**

![图数据库 灰度计划](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/20230927-03.png)

注：

* 配置中心开关控制，有问题随时切换，秒级恢复。
* 读接口遗漏无影响, 只有改到的才会影响。
* 使用参数 hash 值作为 key，确保同一参数多次请求结果一致、满足 abs(key) % 1000 < X ( 0< X < 1000， X 为动态配置 ) 即为命中灰度。

题外话：其实**重构，最重要的就是灰度方案**，这个我在之前文章《浅谈这些年做过的千万级系统重构项目》也提到过。本次灰度方案设计比较完善，大家重点看阶段一、在灰度放量之前，我们用线上真实的流量去异步做数据对比，对比完全通过之后，再放量，本次对比阶段比预期长了很多（实际上用了 2 周时间，发现了很多问题）。

## 6. 数据对比方案 WHICH ONE

### **未命中灰度**

未命中灰度流程如下：

先调用老系统，再根据是否命中采样（采样比例配置 0% ~ 100%），命中采样会发送 MQ，再在新系统消费 MQ，请求新系统接口，于老系统接口返回数据进行 JSON 对比。对比不一致，发送企业微信通知，实时感知数据不一致，发现并解决问题。

![图数据库 数据对比方案](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/20230927-04.png)

反之亦然！！

## 7. 数据迁移方案 READY？GO！

* 全量（历史数据）：写脚本全量迁移，上线期间产生不一致从 MQ 消费近 3 天数据
* 增量：同步双写（写的接口很少，写请求 QPS 不高）

## 8. 改造案例 - 以子图查询为例 AWOW

改造前：


```
@Override
    public MSubGraphReceive getSubGraph(MSubGraphSend subGraphSend) {
        logger.info("-----start getSubGraph------(" + subGraphSend.toString() + ")");
        MSubGraphReceive r = (MSubGraphReceive) akkaClient.sendMessage(subGraphSend, 30);
        logger.info("-----end getSubGraph:");
        return r;
    }
```

改造后：

**定义灰度模块接口**


```
public interface IGrayService {
    /**
     * 是否命中灰度 配置值 0 ~ 1000  true: 命中  false:未命中
     *
     * @param hashCode
     * @return
     */
    public boolean hit(Integer hashCode);

    /**
     * 是否取样 配置值 0 ~ 100
     *
     * @return
     */
    public boolean hitSample();

    /**
     * 发送请求-响应数据
     * @param requestDTO
     */
    public void sendReqMsg(MessageRequestDTO requestDTO);

    /**
     * 根据
     * @param methodKeyEnum
     * @return
     */
    public boolean hitSample(MethodKeyEnum methodKeyEnum);
}
```

接口改造如下，**kgpCoreService** 请求到 kgp-core 新服务，接口业务逻辑和 orion-x 保持一致、底层图数据库改为查询 NebulaGraph：


```
@Override
    public MSubGraphReceive getSubGraph(MSubGraphSend subGraphSend) {
        logger.info("-----start getSubGraph------(" + subGraphSend.toString() + ")");
        long start = System.currentTimeMillis();
        //1. 请求灰度
        boolean hit = grayService.hit(HashUtils.getHashCode(subGraphSend));
        MSubGraphReceive r;
        if (hit) {
            //2、命中灰度 走新流程
            r = kgpCoreService.getSubGraph(subGraphSend); // 使用Dubbo调用新服务
        } else {
            //这里是原来的流程 使用的akka通信
            r = (MSubGraphReceive) akkaClient.sendMessage(subGraphSend, 30);
        }
        long requestTime = System.currentTimeMillis() - start;

        //3.采样命中了发送数据对比MQ 
        if (grayService.hitSample(MethodKeyEnum.getSubGraph_subGraphSend)) {
            MessageRequestDTO requestDTO = new MessageRequestDTO.Builder()
                    .req(JSON.toJSONString(subGraphSend))
                    .res(JSON.toJSONString(r))
                    .requestTime(requestTime)
                    .methodKey(MethodKeyEnum.getSubGraph_subGraphSend)
                    .isGray(hit).build();
            grayService.sendReqMsg(requestDTO);
        }
        logger.info("-----end getSubGraph: {} ms", requestTime);
        return r;
    }
```

## 9. 项目排期计划 DEADLINE

投入人力: 开发 4 人，测试 1 人

主要事项及耗时如下：

![图数据库 项目排期计划](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/20230927-05.png)

# Part 03. 重构收益

经过团队 2 个月奋斗，目前已完成灰度阶段，收益如下

* NebulaGraph 本身支持分布式扩展，新系统服务支持弹性伸缩，整体支持性能水平扩展；
* 从压测结果看，接口性能提升很明显，可支撑请求远超预期；
* 接入公司统一监控、告警，更利于后期维护。

# Part 04. 总结

本次重构顺利完成，感谢本次一起重构的小伙伴，以及大数据、风控同学支持。同时，也感谢 NebulaGraph 社区 [https://discuss.nebula-graph.com.cn/](https://discuss.nebula-graph.com.cn/)，我们遇到一些问题提问，也很快帮忙解答。

----
**谢谢你读完本文**(///▽///)

如果你想尝鲜图数据库 NebulaGraph，记得去 GitHub 下载、使用、(^з^)-☆ star 它 -> [GitHub](https://github.com/vesoft-inc/nebula)；如果你有更高的性能、易用性、运维实施等方面的需求，你也可以随时 [联系我们](https://www.nebula-graph.com.cn/contact)，获取进一步的帮助哦~

重构图数据库 OrientDB 为 NebulaGraph非常艰难，下面就为大家详细介绍如何重构图数据库？

图数据库系统重构之路：从 OrientDB 迁移到 NebulaGraph 真实案例分享

![Graph RAG: 知识图谱结合 LLM 的检索增强](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2023.38th%20banner_%E7%94%BB%E6%9D%BF%201.jpg)

本文为大家揭示 NebulaGraph 优先提出的 Graph RAG 方法，这种结合知识图谱、图数据库作为大模型结合私有知识系统的最新技术栈，是 LLM+ 系列的第三篇，加上之前的图上下文学习、Text2Cypher 这两篇文章，目前 NebulaGraph + LLM 相关的文章一共有 3 篇。

# Graph RAG

在[第一篇关于上下文学习的博客中](https://discuss.nebula-graph.com.cn/t/topic/13624)我们介绍过，RAG（Retrieval Argumented Generation）这种基于特定任务/问题的文档检索范式中，我们通常先收集必要的上下文，然后利用具有认知能力的机器学习模型进行上下文学习（in-context learning），来合成任务的答案。

借助 LLM 这个只需要”说话“就可以灵活处理复杂问题的感知层，只需要两步，就能搭建一个基于私有知识的智能应用：

- 利用各种搜索方式（比如 Embedding 与向量数据库）从给定的文档中检索相关知识。
- 利用 LLM 理解并智能地合成答案。

而这篇博客中，我们结合最新的探索进展和思考，尝试把 Graph RAG 和其他方法进行比较，说得更透一点。此外，我们决定开始用 Graph RAG 这个叫法来描述它。

> 实际上，[Graph RAG](https://siwei.io/talks/graph-rag-with-jerry/)，是最先由我和 Jerry Liu 的[直播研讨会讨论](https://www.youtube.com/watch?v=bPoNCkjDmco)和[相关的讨论的 Twitter Thread](https://twitter.com/wey_gu/status/1673362774930628608) 中提到的，差不多的内容我在 [NebulaGraph 社区直播](https://www.bilibili.com/video/BV1Pp4y157nt) 中也用中文介绍过。

# 在 RAG 中知识图谱的价值

这部分内容我们在第一篇文章中阐述过，比如一个查询：“告诉我所有关于苹果和乔布斯的事”，基于乔布斯自传这本书进行问答，而这个问题涉及到的上下文分布在自传这本书的 30 页（分块）的时候，传统的“分割数据，Embedding 再向量搜索”方法在多个文档块里用 TOP-K 去搜索的方法很难得到这种分散，细粒的完整信息。而且，这种方法还很容易遗漏互相关联的文档块，从而导致信息检索不完整。

除此之外，在之后一次技术会议中，我有幸和 [leadscloud.com](https://www.leadscloud.com/) 的徐旭讨论之后（他们因为有知识图谱的技术背景，也做了和我们类似的探索和尝试！），让我意识到**知识图谱可以减少基于嵌入的语义搜索所导致的不准确性**。徐旭给出的一个有趣的例子是“保温大棚”与“保温杯”，尽管在语义上两者是存在相关性的，但在大多数场景下，这种通用语义（Embedding）下的相关性常常是我们不希望产生的，进而作为错误的上下文而引入“幻觉”。

这时候，保有领域知识的知识图谱则是非常直接可以缓解、消除这种幻觉的手段。

# 用 NebulaGraph 实现 Graph RAG

一个简单的 Graph RAG 可以如下去简单实现：

1. 使用 LLM（或其他）模型从问题中提取关键实体
2. 根据这些实体检索子图，深入到一定的深度（例如，2）
3. 利用获得的上下文利用 LLM 产生答案。

对应的伪代码可能是这样：

```python
# 伪代码

def _get_key_entities(query_str, llm=None ,with_llm=True):
    ...
    return _expand_synonyms(entities)

def _retrieve_subgraph_context(entities, depth=2, limit=30):
    ...
    return nebulagraph_store.get_relations(entities, depth, limit)

def _synthesize_answer(query_str, graph_rag_context, llm):
    return llm.predict(PROMPT_SYNTHESIZE_AND_REFINE, query_str, graph_rag_context)

def simple_graph_rag(query_str, nebulagraph_store, llm):
    entities = _get_key_entities(query_str, llm)
    graph_rag_context = _retrieve_subgraph_context(entities)
    return _synthesize_answer(
        query_str, graph_rag_context, llm)
```

然而，有了像 LlamaIndex 这样方便的 LLM 编排工具，开发者可以专注于 LLM 的编排逻辑和 pipeline 设计，而不用亲自处理很多细节的抽象与实现。

所以，用 LlamaIndex，我们可以轻松搭建 Graph RAG，甚至整合更复杂的 RAG 逻辑，比如 [Graph + Vector RAG](https://gpt-index.readthedocs.io/en/latest/examples/index_structs/knowledge_graph/KnowledgeGraphIndex_vs_VectorStoreIndex_vs_CustomIndex_combined.html)。

![](https://github.com/siwei-io/talks/assets/1651790/f783b592-7a8f-4eab-bd61-cf0837e83870)

在 LlamaIndex 中，我们有两种方法实现 Graph RAG：

- `KnowledgeGraphIndex` 只用来对任何私有数据从零构建知识图谱（基于 LLM 或者其他语言模型），再 4 行代码进行 Graph RAG：

```
graph_store = NebulaGraphStore(
    space_name=space_name,
    edge_types=edge_types,
    rel_prop_names=rel_prop_names,
    tags=tags,
)
storage_context = StorageContext.from_defaults(graph_store=graph_store)

# Build KG
kg_index = KnowledgeGraphIndex.from_documents(
    documents,
    storage_context=storage_context,
    max_triplets_per_chunk=10,
    space_name=space_name,
    edge_types=edge_types,
    rel_prop_names=rel_prop_names,
    tags=tags,
)

kg_query_engine = kg_index.as_query_engine()
```

- `KnowledgeGraphRAGQueryEngine` 则可以在任何已经存在的知识图谱上进行 Graph RAG。不过，我还没有完成这个 [PR](https://github.com/jerryjliu/llama_index/pull/7204)。

```
graph_store = NebulaGraphStore(
    space_name=space_name,
    edge_types=edge_types,
    rel_prop_names=rel_prop_names,
    tags=tags,
)
storage_context = StorageContext.from_defaults(graph_store=graph_store)

graph_rag_query_engine = KnowledgeGraphRAGQueryEngine(
    storage_context=storage_context,
)
```

最后，我做了[一个 Streamlit 的 Demo](https://www.siwei.io/demos/graph-rag/)来比较 Graph RAG 与 Vector RAG，从中我们可以看到 Graph RAG 并没有取代 Embedding、向量搜索的方法，而是增强了/补充了它的不足。

![](https://www-cdn.nebula-graph.com.cn/nebula-blog/graph-rag/demo.gif)

# Text2Cypher

基于图谱的 LLM 的另一种有趣方法是 Text2Cypher。这种方法不依赖于实体的子图检索，而是将任务/问题翻译成一个面向答案的特定图查询，和我们常说的 Text2SQL 方法本质是一样的。

## 在 NebulaGraph 上进行 Text2Cypher

在之前的文章中我们已经介绍过，得益于 LLM，实现 Text2Cypher 比传统的 ML 方法更为简单和便宜。

比如，[LangChain: NebulaGraphQAChain](https://python.langchain.com/docs/use_cases/more/graph/graph_nebula_qa) 和 [Llama Index: KnowledgeGraphQueryEngine](https://gpt-index.readthedocs.io/en/latest/examples/query_engine/knowledge_graph_query_engine.html) 让我们 3 行代码就能跑起来 Text2Cypher。

## 比较 Text2Cypher 和 (Sub)Graph RAG

这两种方法主要在其检索机制上有所不同。Text2Cypher 根据 KG 的 Schema 和给定的任务生成图形模式查询，而 SubGraph RAG 获取相关的子图以提供上下文。

两者都有其优点，为了大家更直观理解他们的特点，我做了这个 Demo 视频：

我们可以看到两者的图查询模式在可视化下是有非常清晰的差异的。

![](https://www-cdn.nebula-graph.com.cn/nebula-blog/graph-rag/demo2.gif)

## 结合 Text2Cypher 的 Graph RAG

然而，两者并没有绝对的好与坏，不同场景下，它们各有优劣。

在现实世界中，我们可能并不总是知道哪种方法更有效（用来区分应该用哪一种），因此，我倾向于考虑同时利用两者，这样获取的两种检索结果作为上下文，一起来生成最终答案的效果可能是最好的。

具体的实现方法在[这个 PR](https://github.com/jerryjliu/llama_index/pull/7204)中已经可以做到了，只需要设置 `with_text2cypher=True`，Graph RAG 就会包含 Text2Cypher 上下文，敬请期待它的合并。


# 结论

通过将知识图谱、图存储集成到 LLM 技术栈中，Graph RAG 把 RAG 的上下文学习推向了一个新的高度。它能在 LLM 应用中，通过利用现有（或新建）的知识图谱，提取细粒度、精确调整、领域特定且互联的知识。

请继续关注图谱和 LLM 领域的更深入的探索和进一步的发展。

----
**谢谢你读完本文**(///▽///)

如果你想尝鲜图数据库 NebulaGraph，记得去 GitHub 下载、使用、(^з^)-☆ star 它 -> [GitHub](https://github.com/vesoft-inc/nebula)；如果你有更高的性能、易用性、运维实施等方面的需求，你也可以随时 [联系我们](https://www.nebula-graph.com.cn/contact)，获取进一步的帮助哦~

本文为大家揭示 NebulaGraph 优先提出的 Graph RAG 方法，这种结合知识图谱、图数据库作为大模型结合私有知识系统的最新技术栈，是 LLM+ 系列的第三篇。

Graph RAG: 知识图谱结合 LLM 的检索增强

本文整理自 NebulaGraph 布道师 wey 在「夜谈 LLM」主题分享上的演讲，主要包括 LLM 和Graph RAG、知识抽取、Text2Cypher 等技术介绍及未来规划。

关于 LLM 和图、图数据库的那些事

高效建模、快速导入、性能优化——应该怎么做？

使用秘籍 ｜你可能不知道的 NebulaGraph 最佳性能姿势

![图数据库 NebulaGraph 的内存管理实践之 Memory Tracker](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/memory-tracker-banner.jpg)

数据库的内存管理是数据库内核设计中的重要模块，内存的可度量、可管控是数据库稳定性的重要保障。同样的，内存管理对图数据库 NebulaGraph 也至关重要。

图数据库的多度关联查询特性，往往使图数据库执行层对内存的需求量巨大。本文主要介绍 NebulaGraph v3.4 版本中引入的新特性 Memory Tracker，希望通过 Memory Tracker 模块的引入，实现细粒度的内存使用量管控，降低 graphd 和 storaged 发生被系统 OOM kill 的风险，提升 NebulaGraph 图数据库的内核稳定性。

注：为了同代码保持对应，本文部分用词直接使用了英文，e.g. reserve 内存 quota。

# 可用内存

在进行 Memory Tracker 的介绍之前，这里先介绍下相关的背景知识：可用内存。

## 进程可用内存

在这里，我们简单介绍下各个模式下，系统是如何判断可用内存的。

**物理机模式**

数据库内核会读取系统目录 `/proc/meminfo`，来确定当前环境的实际内存和剩余内存，Memory Tracker 将“实际物理内存”作为“进程可以使用的最大内存”；

**容器/cgroup 模式**

在 `nebula-graphd.conf` 文件中有一个配置项 `FLAG_containerized` 用来判断是否数据库跑在容器上。将 `FLAG_containerized`（默认为 false）设置为 true 之后，内核会读取相关 cgroup path 下的文件，确定当前进程可以使用多少内存；cgroup 有 v1、v2 两个版本，这里以 v2 为例；

| FLAG                               | 默认值                        | 解释                           |
| :--------------------------------- | :---------------------------- | :----------------------------- |
| FLAG_cgroup_v2_memory_max_path     | /sys/fs/cgroup/memory.max     | 通过读取路径确定最大内存使用量 |
| FLAG_cgroup_v2_memory_current_path | /sys/fs/cgroup/memory.current | 通过读取路径确定当前内存使用量 |

举个例子，在单台机器上分别控制 graphd 和 storaged 的内存额度。你可以通过以下步骤：

step1：设置 `FLAG_containerized=true`；

step2：创建 `/sys/fs/cgroup/graphd/`，`/sys/fs/cgroup/storaged/`，并配置各自目录下的 `memory.max`；

step3：在 `etc/nebula-graphd.conf`，`etc/nebula-storaged.conf` 添加相关配置

```
--containerized=true
--cgroup_v2_controllers=/sys/fs/cgroup/graphd/cgroup.controllers
--cgroup_v2_memory_stat_path=/sys/fs/cgroup/graphd/memory.stat
--cgroup_v2_memory_max_path=/sys/fs/cgroup/graphd/memory.max
--cgroup_v2_memory_current_path=/sys/fs/cgroup/graphd/memory.current
```

## Memory Tracker 可用内存

在获取“进程可用内存”以后，系统需要将其换算成 Memory Tracker 可 track 的内存，“进程可用内存”与“Memory Tracker 可用内存”有一个换算公式；

memtracker_limit = ( total - FLAGS_memory_tracker_untracked_reserved_memory_mb ) *  FLAGS_memory_tracker_limit_ratio

![usable_memory](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/memory-tracker/usable_memory.png)

| **FLAG**                                    | **默认值** | **解释**                                                     | **支持动态改** |
| :------------------------------------------ | ---------- | ------------------------------------------------------------ | -------------- |
| memory_tracker_untracked_reserved_memory_mb | 50 M        | Memory Tracker 会管理通过 new/delete 申请的内存，但进程除了通过此种方式申请内存外，还可能存在其他方式占用的内存；比如通过调用底层的 malloc/free 申请，这些内存通过此 flag 控制，在计算时会扣除此部分未被 track 的内存。 | Yes            |
| memory_tracker_limit_ratio                  | 0.8        | 指定 Memory Tracker 可以使用的内存比例，在一些场景，我们可能需要调小来防止 OOM。 | Yes            |

这里来详细展开说下 `memory_tracker_limit_ratio` 的使用：

- 在混合部署环境中，存在多个 graphd 或 storaged 混合部署是需要调小。比如 graphd 只占用 50% 内存，则需在 nebula-graphd.conf 中将其手动改成 0.5；
- 取值范围：`memory_tracker_limit_ratio` 除了 `(0,1]` 取值范围外，还额外定义了两个特殊值：
   - `2`：通过数据库内核感知当前系统运行环境的可用内存，动态调整可用内存。由于此种方式非实时，有一定的概率会感知不精准；
   - `3`：limit 将被设成一个极大值，起到关闭 Memory Tracker 的效果；

# Memory Tracker 的设计与实现方案

下面，讲下 Memory Tracker 的设计与实现。整体的 Memory Tracker 设计，包含 **Global new/delete operator**、**MemoryStats**、**system malloc**、**Limiter** 等几个子模块。这个部分着重介绍下 Global new/delete operator 和 MemoryStats 模块。

![memory_tracker](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/memory-tracker/memory_tracker.png)

## Global new/delete operator

Memory Tracker 通过 overload 全局 new/delete operator，接管内存的申请和释放，从而做到在进行真正的内存分配之前，进行内存额度分配的管理。这个过程分解为两个步骤：

- 第一步：通过 MemoryStats 进行内存申请的汇报；
- 第二步：调用 jemalloc 发生真正的内存分配行为；

> **jemalloc**：Memory Tracker 不改变底层的 malloc 机制，仍然使用 jemalloc 进行内存的申请和释放；

## MemoryStats

全局的内存使用情况统计，通过 GlobalMemoryStats 和 ThreadMemoryStats 分别对全局内存和线程内部内存进行管理；

### ThreadMemoryStats

`thread_local` 变量，执行引擎线程在各自的 ThreadMemoryStats 中维护线程的 MemoryStats，包括“内存 Reservation 信息”和“是否允许抛异常的 throwOnMemoryExceeded”；

- **Reservation**

每个线程 reserve 了 1 MB 的内存 quota，从而避免频繁地向 GlobalMemoryStats 索要额度。不管是申请还是返还时，ThreadMemoryStats 都会以一个较大的内存块作为与全局交换的单位。  

**alloc**：在本地 reserved 1 MB 内存用完了，才问全局要下一个 1 MB。通过此种方式来尽可能降低向全局 quota 申请内存的频率；

**dealloc**：返还的内存先加到线程的 reserved 中，当 reserve quota 超过 1 MB 时，还掉 1 MB，剩下的自己留着；

```
 // Memory stats for each thread.
 struct ThreadMemoryStats {
   ThreadMemoryStats();
   ~ThreadMemoryStats();
 
   // reserved bytes size in current thread
   int64_t reserved;
   bool throwOnMemoryExceeded{false};
 };
```

- **throwOnMemoryExceeded**  

线程在遇到超过内存额度时，是否 throw 异常。只有在设置 `throwOnMemoryExceeded` 为 true 时，才会 `throw std::bad_alloc`。需要关闭 `throw std::bad_alloc` 场景见 `Catch std::bac_alloc` 章节。

### GlobalMemoryStats

全局内存额度，维护了 limit 和 used 变量。

- **limit**：通过运行环境和配置信息，换算得到 Memory Tracker 可管理的最大内存。limit 同 Limiter 模块的作用，详细内存换算见上文“Memory Tracker 可用内存”章节；

- **used**：原子变量，汇总所有线程汇报上来的已使用内存（包括线程 reserved 的部分）。如果 used + try_to_alloc > limit，且在 `throwOnMemoryExceeded` 为 true 时，则会抛异常`std::bac_alloc`。

# Catch std::bac_alloc

由于 Memory Tracker overload new/delete 会影响所有线程，包括三方线程。此时，`throw bad_alloc` 在一些第三方线程可能出现非预期行为。为了杜绝此类问题发生，我们采用在代码路径上主动开启内存检测，选择在算子、RPC 等模块主动开启内存检测；

## 算子的内存检测

在 graph/storage 的各个算子中，添加 `try...catch` (在当前线程进行计算/分配内存) 和 `thenError` (通过 `folly::Executor` 异步提交的计算任务)，感知 Memory Tracker 抛出 `std::bac_alloc`。数据库再通过 Status 返回错误码，使查询失败；

在进行一些内存调试时，可通过打开 `nebula-graphd.conf` 文件中的 `FLAGS_memory_tracker_detail_log` 配置项，并调小 `memory_tracker_detail_log_interval_ms` 观察查询前后的内存使用情况；

**folly::future 异步执行**

```c++
thenValue([this](StorageRpcResponse<GetNeighborsResponse>&& resp) {
    memory::MemoryCheckGuard guard;
    // memory tracker turned on code scope
    return handleResponse(resp);
})
.thenError(folly::tag_t<std::bad_alloc>{},
    [](const std::bad_alloc&) {
    // handle memory exceed
})
```

**同步执行**

```c++
memory::MemoryCheckGuard guard; \
try {
    // ...
} catch (std::bad_alloc & e) { \
    // handle memory exceed
}
```

## RPC 的内存检测

RPC 主要解决 Request/Response 对象的序列化/反序列化的内存额度控制问题，由于 storaged reponse 返回的数据均封装在 DataSet 数据结构中，所以问题转化为：DataSet 的序列化、反序列化过程中的内存检测。

**序列化**：DataSet 的对象构造在 NebulaGraph 算子返回结果逻辑中，默认情况下，已经开启内存检测；

**反序列化**：通过 `MemoryCheckGuard` 显式开启，在 `StorageClientBase::getResponse's onError` 可捕获异常；

# 错误码

为了便于分辨哪个模块发生问题，NebulaGraph 中还添加了相关错误码，分别表示 graphd 和 storaged 发生 memory exceeded 异常：

```
E_GRAPH_MEMORY_EXCEEDED = -2600, // Graph memory exceeded
E_STORAGE_MEMORY_EXCEEDED = -3600, // Storage memory exceeded
```

# 延伸阅读

* 什么是 malloc 以及动态内存分配：[https://en.wikipedia.org/wiki/C_dynamic_memory_allocation](https://en.wikipedia.org/wiki/C_dynamic_memory_allocation)
* jemalloc
    * 原始论文：[https://www.bsdcan.org/2006/papers/jemalloc.pdf](https://www.bsdcan.org/2006/papers/jemalloc.pdf)
    * Facebook 对 jemalloc 的优化：[https://engineering.fb.com/2011/01/03/core-data/scalable-memory-allocation-using-jemalloc/](https://engineering.fb.com/2011/01/03/core-data/scalable-memory-allocation-using-jemalloc/)

---

**谢谢你读完本文** (///▽///)

想要来体验下最新版的 v3.4.0 么？NebulaGraph Desktop，Windows 和 macOS 用户安装图数据库的绿色通道，10s 拉起搞定海量数据的图服务。通道传送门：http://c.nxw.so/c0svX

想看源码的小伙伴可以前往 GitHub 阅读、使用、(^з^)-☆ star 它 -> [GitHub](http://c.nxw.so/8yTlk)；和其他的 NebulaGraph 用户一起交流图数据库技术和应用技能，留下[「你的名片」](http://c.nxw.so/9jvQN)一起玩耍呢~

本文主要介绍 NebulaGraph v3.4 版本中引入的新特性 Memory Tracker，希望通过 Memory Tracker 模块的引入，实现细粒度的内存使用量管控，降低 graphd 和 storaged 发生被系统 OOM kill 的风险，提升 NebulaGraph 图数据库的内核稳定性。

图数据库 NebulaGraph 的内存管理实践之 Memory Tracker

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/images/blogs/2023.12th%20banner_%E7%94%BB%E6%9D%BF%201.jpg) 

在进行各种图处理、图计算、图查询的时候，内存或是硬盘中如何存储图结构是一个影响性能的关键因素。本文主要分析了几种常见的内存图结构，及其时间、空间复杂度，希望对你有所启发。

通常来说，对于图结构的几种常见的基础操作：

1. 插入一个点
2. 插入一个边
3. 删除一个边
4. 删除一个点的全部邻边
5. 找到一个点的全部邻边
6. 找到一个点的另一个邻点
7. 全图扫描
8. 获取一个点的入度或者出度

这些图相关的操作，除了要关心时间复杂度之外，需要考虑空间占用的问题。

对于大多数实时读写型的系统，增删改查的性能问题会比较重要，它们比较关注上面 1-6 的操作；对于部分密集计算的系统，对批量读取的性能会比较重视，侧重上面 5-8 的操作。

不过遗憾的是，无论是常规的图查询，还是进阶的图计算，根据 RUM 猜想[1]，读快、写快、又省空间这样”既要又要也要”的好事是不存在的。

下面，我们介绍几个数据结构并给出少量的定量分析。

我们先从三个典型的方案（邻接矩阵、压缩稀疏矩阵和邻接表）说起，再介绍几种近几年的研究的变种结构 PCSR、VCSR、CSR++。

# 邻接矩阵 Adjacency Matrix

用矩阵来表示图结构是大学里数据结构课程中都学过的知识，也是一种非常直观的办法。

点 i 与点 j 之间有一条边，等价对应于矩阵上 $M_{ij}$ 为 1。当然，这里的点 ID 是需要连续排列无空洞。

用矩阵来表示图结构有明显的好处，可以复用大量线性代数的研究成果：比如图上模式匹配类的问题等价于矩阵的相乘。

下面是一个模式匹配问题，它的大体意思是在全图上寻找这样一种图结构：

```shell
Match (src)-[friend * 2..4]->(fof)
WHERE src.age > 30
RETURN fof
```

对于这样一个问题可以直接对应右边的矩阵操作：

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/image1.jpg)

比如，2 跳遍历等价于矩阵 F 自乘；2 - 4 跳遍历分别等价于 F^2、F^3、F^4；取属性等价于乘以一个过滤矩阵。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/image2.png)

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/image3.png)

更进一步，由于矩阵操作是天生可以分块并行加速，这在性能上有极大的优势。

下面，我们对邻接矩阵操作进行一个简单的定量分析

|操作|时间复杂度|备注|
|----|----|----|
|插入一个点|O(n^2)|对于矩阵来说，增加一个点意味着整个矩阵的维度增加，通常需要另外开辟一块空间|
|插入一个边|O(1)|增加一个边只是将对应的位置置 1|
|删除一个边|O(1)|置0|
|删除一个点的全部邻边|O(n)|对于某个点所有出边的删除对应某一行的置0。入边对应某一列，可以批量操作|
|找到一个点的全部邻边|O(n)||
|找到一个点的给定邻点|O(1)||
|全图扫描|O(n^2)||

其中，n=|V|，m=|E|。

优化上，批量操作（CPU Cache/SSD block）可以线性增加性能，例如 O(n) 可以降低到 O(n/B)，但不影响定量分析。

**由于绝大多数图结构是极其稀疏的，因此简单用邻接矩阵来表示图结构，其内存会有夸张的浪费**。更为严重的是，当有多种边类型时，每种边类型各需要一个邻接矩阵。这使得裸用矩阵在实际情况中只能处理很小数据量的场景。当然，对于现代服务器动辄几百 G 的内存，如果只有几亿点边的数据量，像是 twitter2010，这并不会是很严重的问题。但大多数情况下，条件允许的话，大家还是希望找到一些更加经济的结构。

# 压缩稀疏矩阵 CSR/CSC

压缩稀疏矩阵是一种非常流行和紧凑的图结构表示方式，大多数图计算系统都采用 CSR。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/image5.png)

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/image4.png)

这里简单介绍一下 CSR 的结构：

对于点 IDx，取邻居 ID 就是 F[N[x]] 到 F[N[x+1]-1]。

例如，查找点 ID2 的邻居，对应为 F[N[2]] 到 F[N[2+1]-1]，对应到上图也即 1 6 8。查找点 ID7 的邻居，对应为 F[N[7]] 到 F[N[7+1]-1]，也就是 2 和 4。 

另外，CSR 记录的仅是出边的信息，如果要考虑入边就使用 CSC，其原理是类似的。

|操作|时间复杂度|备注|
|----|----|----|
|插入一个点|O(1)|在点矢量尾部增加|
|插入一个边 <u,v>|O(m+n)|边矢量，从 u 对应的邻居开始，都向后移动一位；点矢量，从 u 对应位置开始每个值加 1|
|删除一个边|O(m+n)|插入边的逆过程|
|删除一个点 v 的全部邻边|O(m+n)|边矢量移动 deg(v) 位，点矢量 u 对应位置置 0|
|找到一个点的全部邻边|O(deg(v))||
|找到一个点的给定邻点|O(log(deg(v)))|deg(v) 内的排序查找|
|全图扫描|O(m+n)||

CSR 的空间占用是 O(|V|+|E|)，**在空间节省和顺序查找上是极其高效的**。但**在大量插入时，压缩稀疏矩阵和邻接矩阵一样，需要重新开辟空间，效率很低**。所以，它适合于计算密集场景但不适合增改频繁的场景。

CSR 还有一个显著的优点是可以快速获取每个点的出入度，只要计算 N[x+1]-N[x]，这在判断一些点是否为超级节点时很方便。如果不是稀疏矩阵的话，通常会用另外一个单独的结构来记录出入度。

此外，CSR 不容易实现并发修改，其每次插入都需要对两个矢量进行位移，这并不高效。

这里推荐两个相关的开源项目，可以进一步了解下 CSR 的使用：

* [https://github.com/DrTimothyAldenDavis/GraphBLAS](https://github.com/DrTimothyAldenDavis/GraphBLAS)
* [https://github.com/GraphBLAS/LAGraph](https://github.com/GraphBLAS/LAGraph)

# 邻接链表 Adjacency List

和基于矩阵的方式不同，邻接链表 AL 空间上有优势，但对于边的读写上会略微慢一点（指针在内存中不能连续移动）。AL 的做法是把邻边（出边）用 list 或者有序 list 的方式串连起来。由此延伸的一个变种是邻边从 list 改为 array。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/image7.png)

|操作|时间复杂度|备注|
|----|----|----|
|插入一个点|O(1)|尾插入|
|插入一个边 <u,v>|O(log(deg(u))) |有序 list|
|删除一个边 |O(log(deg(u)))||
|删除一个点 v 的全部邻边 |O(1)||
|找到一个点的全部邻边|O(deg(u))||
|找到一个点的给定邻点|O(log(deg(u)))||
|全图扫描 |O(n+m)||

AL 相比 CSR 通常不能直接获得点的出入度，可以通过可以单独维护一个字段实现该功能。

此外，邻接表并不需要 ID 连续排布，对于频繁增删点的场景特别友好。AL 对于并发修改的支持也更友好，天然在点级别有并行度。当然，对于超级节点，直接用 list 的方式，还是会有些性能的问题要考虑；优化上可能会进一步改造成 Blocked list 的方式，可以带来更好的数据局部性和细颗粒度。

由于 ID 不用严格连续排布，AL 的一个常见变种就是 Tree。

# Tree

在这种结构中，一个点和其所有的邻边被建模成了 key-value，key 是点 ID，value 是所有邻边的编码。Key 通过 Tree 的方式组织在一起。这里的树可以是 B-Tree 等各变种 Tree。虽然本文没有讨论图属性，但 value 中也是可以存放 value。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/image6.png)

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/image9.png)


|操作|时间复杂度|备注|
|----|----|----|
|插入一个点 |O(log(n))||
|插入一个边 <u,v>|O(deg(u) log(n))||
|删除一个边|O(deg(u) log(n))||
|删除一个点 v 的全部邻边|O(log(n))||
|找到一个点的全部邻边|O(deg(u) log(n))||
|找到一个点的给定邻点|O(log(n deg(u))||
|全图扫描|O(n+m)||

为了控制访问颗粒度，每个叶子通常会被限定为固定的大小（页）。这就是在数据库类系统里面最常见的办法 B-tree。为了增改方便，也可以把每页的 in-place update 改成 Copy-On-Write 的方式；一个典型的代表就是 LLAMA[2]，但这种多版本的读取通常会需要更多的空间，并且当有大量累积修改时，需要定期的多版本合并以降低跨快照读。某种程度上，它和 LSM-Tree 的思路有些接近。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/image8.png)

# 基于 CSR 的变种 PCSR 和 VCSR

由于 CSR 在空间和读性能上有很大的优势，但在插入时的耗时和空间上都很弱，因此本节几个变种的主要目的都是为了改善其弱项，大体思路都是分块和 buffer。

在 CSR 的边矢量进行增删时可以注意到，主要耗时是在对于矢量的元素位移上。因此，一个直观的思路是预留一些插入空白位，在删除时也不立刻回收这些空白。

而分块思想，是指将一些局部数据放在同一个分块内，例如 Tree 中每个 page 就是一种分块的方式。与此对应的是，buffer 空白之间的连续区域。

## PCSR

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/image12.png)

PCSR [3]的基本思想是：对于点矢量，其元素从一个值改为对应边矢量中对应邻边位置的 `<起点,终点>`。而对于边矢量，在这些分块所对应边界放置哨兵 sentinel，上图中的 S，上图的 “-“ 对应预留插入位置留空。

事实上，原文中，对于边矢量，其本质是实现为一个 B-Tree，本文先简化成一个 Array。  

|操作|时间复杂度|备注|
|----|----|----|
|插入一个点| O(1)| 直接在点矢量和边矢量的尾插入|
|插入一个边 <u,v>| O(log(deg(u))| 边矢量对应分片的二分+空位查找|
|删除一个边| O(log(deg(u))||
|删除一个点v的全部邻边 |O(1) |边矢量对应分片置空，点矢量对应 ID 位置置空|
|找到一个点的全部邻边| O(deg(u))||
|找到一个点的给定邻点| O(log(deg(u))||
|全图扫描| O(n+m)||

可以看到，PCSR 的预留位置多少都是需要重平衡，不能过多也不能不足。特别是大批量增删时，对预留位置的处理会是一个较重的操作。

此外，如果把 PMA 的 B-Tree 以及需要 rebalance 的本质考虑进去，其和前述 Tree 方式的区别并不是很大。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/image10.png)
 
## VCSR 

VCSR[4]主要是对 PCSR 的一个改进，其朴素思想是 PCSR 的留空是均匀的，而大多数图结构的出入度，是存在 20-80 这样的幂率特征，而 PCSR 的一个主要痛点是频繁的 rebalance。VCSR 的做法是为每个分块预留空间正比于其分块内的点的数量，即：边矢量中，一个分块内，如果点的数量多，就多预留一些空位。在直觉上，点数量多时，其分块对应的边插入会更多一些，这样可以减少 rebalance 的频率。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/image11.png)

此外，VCSR 还有些版本号之类的优化。

## CSR++

事实上，CSR++[5]在设计上其实更接近一种 AL/Tree 的变种，而不是 CSR。它主要有三个方面的优化：

第一，对于 Vertex Array 再分段，将一个大的 Array 拆成多段，这样可以有更细的读写颗粒度。通过 `段 ID + 点 ID` 来定位每个点和其邻边。
第二，Vertex Array 中每个元素，**除了记录点 ID 之外，对于邻边数量很少的点，直接把邻居 ID 也对齐地塞 inline 进去**。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/csr++format.png)

对于大多数的点，其邻边就不需要单独的 Edge Array 来存储了。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/csr++format-link-edge.png)

可以看到这种方式在图比较稀疏的时候，对于 CPU Cache 扫描是很友好的。

第三，对于每个点的邻边，采用copy-on-write、标记删除等常见的优化办法，构建成类似 `std::vector` 结构。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/image13.png)

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/image14.png)

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/image15.png)

# 小结

最后，由于在图查询、图存储和图计算不同场景下，对于图结构的读写扫描和生命周期都有些不同的要求，不同的数据结构也有不同的优劣。

当然，本文只是讨论了图结构可以放在内存中的情况。当不得不把部分数据放在硬盘上时，问题就完全不同了。当然本文也没有讨论不同 CPU 对于不同距离内存的性能差异 NUMA，或者跨进程通信带来的影响。

# 延伸阅读

最后，我们来了解下在图计算/图算法上的图操作。

## 图算法中的图操作

在图计算中，存在多种图结构算法，可能会涉及多种基础操作。

中心性 Centrality Algorithms，一种衡量一个节点在整个网络图中所在中心程度的算法，包括：度中心性、接近中心性、介数中心性等，会涉及“找到一个点的全部邻边”、“找到一个点的另一个邻点”、“全图扫描”的操作组合。

* 度中心性通过节点的度数，即关联的边数来刻画节点的受欢迎程度，这将会要求找到一个点的所有邻边。
* 接近中心性，通过计算每个节点到全图其他所有节点的路径和来刻画节点与其他所有节点的关系密切程度，这将会要求进行全图扫描，查找点和图中所有点的路径信息。
* 介数中心性，则用于衡量一个顶点出现在其他任意两个顶点对之间最短路径上的次数，从而来刻画节点的重要性，这将会要求进行全图扫描，找到一个点和它的邻点及路径信息

PageRank，又称网页排名、谷歌左侧排名，是一种由搜索引擎根据网页之间相互的超链接计算的技术作为网页排名的要素之一的排名方法。它以 Google 公司创办人拉里·佩奇 Larry Page 之姓来命名。Google 用它来体现网页的相关性和重要性，在搜索引擎优化操作中是经常被用来评估网页优化的成效因素之一。一般来说，PageRank 的值越高，表示其被很多其他网页链接到，说明它的重要性很高；而如果一个 PageRank 很高的网页链接到其他网页，被链接的网页的 PageRank值也会随之提高。PageRank 的计算过程如下：

假设由 4 个网页组成的集合：A、B、C、D，每个页面的初始 PageRank 值相同，为了满足概率值为 0-1 之间，假设这个值为 0.25。

如果所有页面都只链接至 A，如下图，则 A 点的值将是 B、C、D 的 PageRank 值的和。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/pagerank-links.png)

倘若是下图这种图结构：

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/abcd-relations.png)

B 链接到 C，D 链接到 B 和 C，A 点的值计算的方式如下：

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/pagerank-a-pr.png)

这里的 2、1、3，分别是 B 点对外链接的 2 条边，C 点对外链接的 1 条边，D 点对外链接的 3 条边。

换句话说，算法将根据每个页面连出总数平分该页面的 PR 值，并将其加到其所指向的页面：

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/pagerank-formula.png)

最后，所有这些 PR 值被换算成百分比形式再乘上一个修正系数。

由于“没有向外链接的网页”传递出去的 PR 值会是0，这时候如果递归的话，会导致指向它的页面的 PR 值的计算结果同样为零，所以 PageRank 会赋给每个页面一个最小值。

因此，一个页面的 PR 值直接取决于指向它的的页面。如果在最初给每个网页一个随机且非零的 PR 值，经过重复计算，这些页面的 PR 值会趋向于某个定值，也就是处于收敛的状态，即最终结果。

简单来说，大多数迭代图计算模型都是基于“找到一个点的全部邻边”、“找到一个点的另一个邻点”操作。

# AIGC 小课堂

在 AIGC 小课堂部分，我们会用 NebulaGraph 接入的 aibot 来讲解下文中的部分概念。你如果对 chatgpt 或者是 aibot 有兴趣，可以来 [https://discuss.nebula-graph.com.cn/](https://discuss.nebula-graph.com.cn/) 向 aibot 提出你的要求。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/what-is-csr.png)

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/graph-data-structure-in-memory/csr-case1.png)

# 参考文献

1. Athanassoulis, M., Kester, M. S., Maas, L. M., et al. (2016). Designing Access Methods: The RUM Conjecture. In EDBT (pp. 461-466).
2. Macko, P., Marathe, V. J., Margo, D. W., et al. (2015). Llama: Efficient Graph Analytics Using Large Multiversioned Arrays. In 2015 IEEE 31st International Conference on Data Engineering (pp. 363-374). IEEE.
3. Wheatman, B., & Xu, H. (2018). Packed Compressed Sparse Row: A Dynamic Graph Representation. In 2018 IEEE High Performance Extreme Computing Conference (HPEC) (pp. 1-7). IEEE.
4. Islam, A. A. R., Dai, D., & Cheng, D. (2022). VCSR: Mutable CSR Graph Format Using Vertex-Centric Packed Memory Array. In 2022 22nd IEEE International Symposium on Cluster, Cloud and Internet Computing (CCGrid) (pp. 71-80). IEEE.
5. Firmli, S., Trigonakis, V., Lozi, J. P., et al. (2020). CSR++: A Fast, Scalable, Update-Friendly Graph Data Structure. In 24th International Conference on Principles of Distributed Systems (OPODIS'20).

在进行各种图处理、图计算、图查询的时候，内存或是硬盘中如何存储图结构是一个影响性能的关键因素。本文主要分析了几种常见的内存图结构，及其时间、空间复杂度，希望对你有所启发。

NebulaGraph 专栏：走进图数据世界，解析内存中的高性能图结构

![NebulaGraph 的 Java 数据解析实践与指导](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/images/blogs/NebulaGraph-Java.jpg)

图数据库 NebulaGrpah 的论坛和微信群里，有不少用户问及了 Java 客户端数据解析的问题。在本文教你一种简单的方式同返回结果交互，快速、即时地拿到解析数据。

# 愉快、干净的 Java 交互环境

本文最为关键步骤之一，便是用几行代码，准备一个干净的交互式 NebulaGraph Java REPL 环境。

多亏了 [Java-REPL](https://github.com/albertlatacz/java-repl/)，我们可以很方便地（像 iPython 那样）去实时交互地调试、分析 NebulaGraph Java 客户端。

下面，开始实操。

先用 Docker 镜像准备环境：

```bash
docker pull albertlatacz/java-repl
docker run --rm -it \
    --network=nebula-net \
    -v ~:/root \
    albertlatacz/java-repl \
    bash
apt update -y && apt install ca-certificates -y
wget https://dlcdn.apache.org/maven/maven-3/3.8.6/binaries/apache-maven-3.8.6-bin.tar.gz --no-check-certificate

tar xzvf apache-maven-3.8.6-bin.tar.gz

wget https://github.com/vesoft-inc/nebula-java/archive/refs/tags/v3.0.0.tar.gz
tar xzvf v3.0.0.tar.gz
cd nebula-java-3.0.0/
../apache-maven-3.8.6/bin/mvn dependency:copy-dependencies
../apache-maven-3.8.6/bin/mvn -B package -Dmaven.test.skip=true

java -jar ../javarepl/javarepl.jar
```

在执行完上面的 `java -jar ../javarepl/javarepl.jar` 之后，我们就进入了交互式的 Java Shell（REPL）。我们不用再做编译、执行、print 这样的慢反馈来调试和研究我们的代码了，是不是很方便？

```java
root@a2e26ba62bb6:/javarepl/nebula-java-3.0.0# java -jar ../javarepl/javarepl.jar

Welcome to JavaREPL version 428 (Java HotSpot(TM) 64-Bit Server VM, Java 1.8.0_111)
Type expression to evaluate, :help for more options or press tab to auto-complete.
Connected to local instance at http://localhost:43707

java> System.out.println("Hello, World!");
Hello, World!
java>
```

首先我们在 `java>` 提示符下，这些来把必须的类路径和导入：

```java
:cp /javarepl/nebula-java-3.0.0/client/target/client-3.0.0.jar
:cp /javarepl/nebula-java-3.0.0/client/target/dependency/fastjson-1.2.78.jar
:cp /javarepl/nebula-java-3.0.0/client/target/dependency/slf4j-api-1.7.25.jar
:cp /javarepl/nebula-java-3.0.0/client/target/dependency/slf4j-log4j12-1.7.25.jar
:cp /javarepl/nebula-java-3.0.0/client/target/dependency/commons-pool2-2.2.jar
:cp /javarepl/nebula-java-3.0.0/client/target/dependency/log4j-1.2.17.jar

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import com.vesoft.nebula.ErrorCode;
import com.vesoft.nebula.client.graph.NebulaPoolConfig;
import com.vesoft.nebula.client.graph.data.CASignedSSLParam;
import com.vesoft.nebula.client.graph.data.HostAddress;
import com.vesoft.nebula.client.graph.data.ResultSet;
import com.vesoft.nebula.client.graph.data.SelfSignedSSLParam;
import com.vesoft.nebula.client.graph.data.ValueWrapper;
import com.vesoft.nebula.client.graph.net.NebulaPool;
import com.vesoft.nebula.client.graph.net.Session;
import java.io.UnsupportedEncodingException;
import java.util.Arrays;
import java.util.List;
import java.util.concurrent.TimeUnit;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.lang.reflect.*;
```

我们可以从这 Java 环境连接到 NebulaGraph。在下面的例子中，我用了自己的 graphd 的 IP 和端口作为例子：

```java
NebulaPoolConfig nebulaPoolConfig = new NebulaPoolConfig();
nebulaPoolConfig.setMaxConnSize(10);
List<HostAddress> addresses = Arrays.asList(new HostAddress("192.168.8.127", 9669));
NebulaPool pool = new NebulaPool();
pool.init(addresses, nebulaPoolConfig);
Session session = pool.getSession("root", "nebula", false);
```

# 通过调用 `execute` 方法获得不太容易懂的 ResultSet 对象

刚接触 NebulaGraph Java 客户端的大家一定对这个 ResultSet 对象有些愁。别担心，借助我们的环境，十分钟把它搞通。这里我们执行一个简单的返回 vertex 顶点的结果看看：

```java
ResultSet resp = session.execute("USE basketballplayer;MATCH (n:player) WHERE n.name==\"Tim Duncan\" RETURN n");
```

我们可以参考 ResultSet 的代码：[client/graph/data/ResultSet.java](https://github.dev/vesoft-inc/nebula-java/blob/master/client/src/main/java/com/vesoft/nebula/client/graph/data/ResultSet.java)

其实可以先不看，跟着教程往下走。一般来说，查询结果都是二维表，ResultSet 针对行和列提供了常见的处理方法。通常，我们会获取每一行结果，再解析它，而关键的问题是每一个值要怎么处理。

```java
java> resp.isSucceeded()
java.lang.Boolean res9 = true

java> resp.rowsSize()
java.lang.Integer res16 = 1

java> rows = resp.getRows()
java.util.ArrayList rows = [Row (
  values : [
    <Value vVal:Vertex (
        vid : <Value sVal:70 6c 61 79 65 72 31 30 30>,
        tags : [
          Tag (
              name : 70 6C 61 79 65 72,
              props : {
                [B@5264a468 : <Value iVal:42>
                [B@496b8e10 : <Value sVal:54 69 6d 20 44 75 6e 63 61 6e>
              }
            )
        ]
      )>
  ]
)]
    
java> row0 = resp.rowValues(0)
java.lang.Iterable<com.vesoft.nebula.client.graph.data.ValueWrapper> res10 = ColumnName: [n], Values: [("player100" :player {name: "Tim Duncan", age: 42})]

```

回到本次 query 语句，它其实是在返回一个 vertex 顶点：

```shell
(root@nebula) [basketballplayer]> match (n:player) WHERE n.name == "Tim Duncan" return n
+----------------------------------------------------+
| n                                                  |
+----------------------------------------------------+
| ("player100" :player{age: 42, name: "Tim Duncan"}) |
+----------------------------------------------------+
Got 1 rows (time spent 2116/44373 us)
```

通过上面的几个方法，我们其实能够获得这个顶点的值：

```java
v = Class.forName("com.vesoft.nebula.Value")
v.getDeclaredMethods()
```

然而，这个 `com.vesoft.nebula.Value` 的值的类提供的方法特别原始，这也是让大家犯愁数据解析的原因。所以，在这个教程中最重要的一个带走的经验（除了利用 REPL 之外）就是：**非必要不要去取这个原始的类，我们应该去取得 `ValueWrapper` 封装之后的值**！！！

> 注意：其实我们有更轻松地方法，就是用 executeJson 直接获得 JSON string。别担心，会在后面提到，不过这个方法要 2.6 之后才支持。

那么问题来了，如何使用 `ValueWrapper` 封装呢？其实答案已经在上面了，大家可以回去看看，`resp.rowValues(0)` 的类型正是 `ValueWrapper` 的可迭代对象！

所以，正确打开方式是迭它！迭它！迭它！其实这个就是代码库里的 GraphClientExample 的一部分例子了，我们把它迭代取出来，放到 `wrappedValueList` 里慢慢把玩：

```java
import java.util.ArrayList;
import java.util.List;
List<ValueWrapper> wrappedValueList = new ArrayList<>();

for (int i = 0; i < resp.rowsSize(); i++) {
    ResultSet.Record record = resp.rowValues(i);
    for (ValueWrapper value : record.values()) {
        wrappedValueList.add(value);
        if (value.isLong()) {
            System.out.printf("%15s |", value.asLong());
        }
        if (value.isBoolean()) {
            System.out.printf("%15s |", value.asBoolean());
        }
        if (value.isDouble()) {
            System.out.printf("%15s |", value.asDouble());
        }
        if (value.isString()) {
            System.out.printf("%15s |", value.asString());
        }
        if (value.isTime()) {
            System.out.printf("%15s |", value.asTime());
        }
        if (value.isDate()) {
            System.out.printf("%15s |", value.asDate());
        }
        if (value.isDateTime()) {
            System.out.printf("%15s |", value.asDateTime());
        }
        if (value.isVertex()) {
            System.out.printf("%15s |", value.asNode());
        }
        if (value.isEdge()) {
            System.out.printf("%15s |", value.asRelationship());
        }
        if (value.isPath()) {
            System.out.printf("%15s |", value.asPath());
        }
        if (value.isList()) {
            System.out.printf("%15s |", value.asList());
        }
        if (value.isSet()) {
            System.out.printf("%15s |", value.asSet());
        }
        if (value.isMap()) {
            System.out.printf("%15s |", value.asMap());
        }
    }
    System.out.println();
}
```

上边这些很丑的 if 就是关键了，我们知道 query 的返回值可能是多种类型的，他们分为：

- 图语义的：点、边、路径
- 数据类型：String，日期，列表，集合…等等

这里的关键是，我们要使用 `ValueWrapper` 为我们准备好 `asXxx` 方法。如果这个值是一个顶点，那么这个 Xxx 就是 Node。同理如果是边的话，这个 Xxx 就是 Relationship。

所以，我给大家看看咱们这个返回点结果的情况下的 `asNode()` 方法：

```java
java> v = wrappedValueList.get(0)
com.vesoft.nebula.client.graph.data.ValueWrapper v = ("player100" :player {name: "Tim Duncan", age: 42})
java> v.asNode()
com.vesoft.nebula.client.graph.data.Node res16 = ("player100" :player {name: "Tim Duncan", age: 42})
java> node = v.asNode()
com.vesoft.nebula.client.graph.data.Node node = ("player100" :player {name: "Tim Duncan", age: 42})
```

顺便说一下，借助于 Java 的反射 reflection，我们可以在这个交互程序里做类似于 Python 里 `dir()` 的事情：实时地去获取一个类支持的方法。像这样，省去了查代码的时间。

```java
java> rClass=Class.forName("com.vesoft.nebula.client.graph.data.ResultSet")
java.lang.Class r = class com.vesoft.nebula.client.graph.data.ResultSet
java> rClass.getDeclaredMethods()
java.lang.reflect.Method[] res20 = [public java.util.List com.vesoft.nebula.client.graph.data.ResultSet.getColumnNames(), public int com.vesoft.nebula.client.graph.data.ResultSet.rowsSize(), public com.vesoft.nebula.client.graph.data.ResultSet$Record com.vesoft.nebula.client.graph.data.ResultSet.rowValues(int), public java.util.List com.vesoft.nebula.client.graph.data.ResultSet.colValues(java.lang.String), public java.lang.String com.vesoft.nebula.client.graph.data.ResultSet.getErrorMessage(), public boolean com.vesoft.nebula.client.graph.data.ResultSet.isSucceeded(), public int com.vesoft.nebula.client.graph.data.ResultSet.getErrorCode(), public java.lang.String com.vesoft.nebula.client.graph.data.ResultSet.getSpaceName(), public int com.vesoft.nebula.client.graph.data.ResultSet.getLatency(), public com.vesoft.nebula.graph.PlanDescription com.vesoft.nebula.client.graph.data.ResultSet.getPlanDesc(), public java.util.List com.vesoft.nebula.client.graph.data.ResultSet.getRows(), public java.lang.String com.vesoft.nebula.client.graph.data.ResultSet.getComment(), public java.lang.String com.vesoft.nebula.client.graph.data.ResultSet.toString(), public boolean com.vesoft.nebula.client.graph.data.ResultSet.isEmpty(), public java.util.List com.vesoft.nebula.client.graph.data.ResultSet.keys()]
```

这样：

```java
java> nodeClass=Class.forName("com.vesoft.nebula.client.graph.data.Node")
java.lang.Class nodeClass = class com.vesoft.nebula.client.graph.data.Node
java> nodeClass.getDeclaredMethods()
java.lang.reflect.Method[] res20 = [public boolean com.vesoft.nebula.client.graph.data.Node.hasTagName(java.lang.String), public boolean com.vesoft.nebula.client.graph.data.Node.hasLabel(java.lang.String), public java.util.List com.vesoft.nebula.client.graph.data.Node.tagNames(), public java.util.HashMap com.vesoft.nebula.client.graph.data.Node.properties(java.lang.String) throws java.io.UnsupportedEncodingException, public java.util.List com.vesoft.nebula.client.graph.data.Node.labels(), public boolean com.vesoft.nebula.client.graph.data.Node.equals(java.lang.Object), public java.lang.String com.vesoft.nebula.client.graph.data.Node.toString(), public java.util.List com.vesoft.nebula.client.graph.data.Node.values(java.lang.String), public int com.vesoft.nebula.client.graph.data.Node.hashCode(), public com.vesoft.nebula.client.graph.data.ValueWrapper com.vesoft.nebula.client.graph.data.Node.getId(), public java.util.List com.vesoft.nebula.client.graph.data.Node.keys(java.lang.String) throws java.io.UnsupportedEncodingException]
```

看到这里，大家应该体会到封装了 `ValueWrapper` 的好处了吧？它提供了方便的符合直觉的方法，对于 Node 类型来说，它提供了 `tagNames()`、`properties()`、`labels()` 等等非常好用的方法：

```java
java> node.properties("player")
java.util.HashMap res11 = {name="Tim Duncan", age=42}
java> node.tagNames()
java.util.ArrayList res12 = [player]
java> node.labels()
java.util.ArrayList res13 = [player]
java> node.values("player")
java.util.ArrayList res14 = [42, "Tim Duncan"]
```

我们这里只展示了顶点数据类型的处理、解析方式（`RETURN n`），像其他的数据类型比如边（edge）、路径（path）或者地理数据、时间数据，用这种方式（看有什么方法，再交互地去试试方法怎么用）也是一样的，对吧？

# 直接返回 JSON 的 `executeJson` 方法

最后，好消息是：从 v2.6 开始，NebulaGraph 可以直接返回 JSON 的 String 了，我们上面的纠结也都不是必要的了：

```java
java> String resp_json = session.executeJson("USE basketballplayer;MATCH (n:player) WHERE n.name==\"Tim Duncan\" RETURN n");

java.lang.String resp_json = "
{
   "errors":[
      {
         "code":0
      }
   ],
   "results":[
      {
         "spaceName":"basketballplayer",
         "data":[
            {
               "meta":[
                  {
                     "type":"vertex",
                     "id":"player100"
                  }
               ],
               "row":[
                  {
                     "player.age":42,
                     "player.name":"Tim Duncan"
                  }
               ]
            }
         ],
         "columns":[
            "n"
         ],
         "errors":{
            "code":0
         },
         "latencyInUs":4761
      }
   ]
}
"
```

我相信大家肯定比我更擅长处理 JSON 的结果了哈~~

# 结论

- 如果你有条件（v2.6 及其以上版本）用 JSON，情况会很容易，甚至你都不太需要本文的方法，不过本文可能会让你的交互环境更容易；
- 如果你不得不和 ResultSet 打交道，记得用 ValueWrapper。因为我们可以用 `asNode()`，`asRelationship()` 和 `asPath()`，封装之后的值比原始的值可爱太多了！
    - 通过 REPL 工具，结合 Java 的 reflection 加上源代码本身，分析数据的处理将变得异常顺滑。

Happy Graphing!

如何快速、即时、符合直觉地去处理 Nebula Java Client 中的数据解析？读这一篇就够了。

NebulaGraph 的 Java 数据解析实践与指导

跨专业、个人独立开发者、“秒回” GitHub 用户 issue…大叶身上的任何一个标签都足以让他人记住他。这次我想借助这次专访的机会，让社区的小伙伴近距离地认识这位社区用户。

不只是他的优秀，更多的是他对技术、理想的执着。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/images/blogs/%E7%94%BB%E6%9D%BF%201%20%E5%89%AF%E6%9C%AC%202.png)

大家好，我是大叶，全名是叶伟城。目前正在写一些开源项目。

但实际上，我并非是科班出生的程序员，因为我之前有一段转专业从生物相关专业转向计算机的经历，所以我比较理解新手，或者是对编程了解不多的人到底面临着什么。因为他们可能没法和我一样，在转专业的过程中，遇到一个不错的导师。很多时候要入行某个领域，其实大多是缺少一个契机，或者是一个带路的人。踏进来之后，他就容易多了，所以临门那一脚很重要，也挺难的。

# 接触 VB 之后发现了程序的乐趣 

在大二之前，电脑对我而言就是一个玩游戏的设备。一切从大二开始就变了，因为我们是综合院校所以开设了一门计算机的专业课——VB，在上课的过程中，我发现原来写程序比玩游戏好玩多。加上那门课的老师人很 Nice，教会了我不少计算机知识。

所以在大二学完之后，我觉得不够、我还要学的更多。于是，大三就开始去蹭计算机的专业课。因为是从头开始学计算机知识，大家一般在大一、大二是打基础的。所以，有段时间我这个大三生就混在青涩的大一班级里上课。但，好在的是，我们学校的计算机老师特别好。不只是在课上传授我知识，只有专业学生才能上的上机实践课，他也让我去参加了。他教授的课程是 Java，跟着他学了一段时间之后，我对 Java 算是有了一点了解。

如果说大三去学计算机是兴趣驱使的，可能后来决心成为一名程序员，更多的是因为我亲眼见证了我们专业（制药工程）的工作环境。大家都知道大四是要实习的，因为我本专业读得是制药工程，自然是要去找实习、跟着导师做些项目。也是那段时间，看过那些药厂、制药环境，我发现我真的要毕业之后的工作，长期待在 GMP 车间里，不是我想要的生活。

所以，同大多数我的同学们实习去专业对口的药厂不同，我其实在整个求职期间都在网上投递简历。这个过程中，收到了一些面试机会。我发现真的工作的所需技能同大学教授的是有所出入的，比如有些公司一面不仅是面编程语言，还有数据库，以及其他方面的专业考核。虽然我也蹭了一些计算机专业课，但和真的科班出身的同学相比，我的计算机体系不够全。

# 被人诟病的培训班也没那么差

意识到这点之后，我开始去接触培训班。在培训班中，从简单的 HelloWorld 开始，到第一条 “select * from table”访问数据库，再到编写一个网页，在这个过程中逐渐完善自己的计算机体系。现在回顾那段时间，状态挺像是高考的，每天 8 点多起来，一直到晚上 10 点多，这样的日子大概经历了有半年的时间。虽然过程看着有点累，但是更多的是快乐，一种知道自己的缺陷并去弥补的乐在其中。

可能大多数人对培训班的印象是“填鸭式”、“搞假简历”，非常功利地学习技术只能直接特定的应用问题。其实我自己对培训班是不带任何有色眼镜的，也是说我是个面试官去面试别人
，不管他是科班的还是非科班、自学的，亦或是培训的，这些背景对我而言都不重要。因为计算机这个领域，说白了很难像其他行业一样，在这块会形成一个壁垒，出身并不重要。

所以，如果你要问我“如果你有选择的话，你还会选择去培训机构吗？”，我的答案应该是：让我回到当年再做决定，其实我依然还会去做这样一个选择。

# 跨专业找工作，第一份工就面成了，还变成了全栈工程师

虽然大学蹭了计算机学生的专业，也在培训班强化了我的计算机体系。但，其实你作为一个跨专业的学生去校招、社招找工作挺难的。

不过我运气还算不错，回厦门之后，面试的第一家公司还算是顺利。因为它是偏业务的，对整个技术要求并不是很高，所以面试问题不算是很深。正是因为它对业务的要求比较高，没有特别高的技术要求。相对来讲，对人的要求也会比较全。不光要写服务端，甚至页面要自己写。不过好在的是，公司会留出时间让你自己去摸索。不管是看视频，或者是看博客，或者其他方式，就在这个探索、学习、实践过程中，慢慢地变成了有比较均衡的技术发展。

像是 Java、Spring 那套体系，基本上掌握得都差不多了，足够满足服务器开发需求。前端这块的话，从一个开始学习 CSS 到 jQuery，再到现在国内比较流行的 Vue.js，它的具体用法和实现原理，都涉猎到了。

像是后来，在前端，或者是大前端领域，我也逐渐接触到了 Flutter，这种跨平台的技术，你写的代码可以变成 Android App 也可以是 iOS App，也能自定义成网页应用。真要说什么弊端的话，大概就是不能做小程序开发。

# 技术渐入佳境，转向自由职业者

在技术逐渐变强的过程中，其实我发现了上班坐班这个事情，自己是真的不喜欢。而且我的作息也同日常的早起上班相冲突，一般我比较晚起。而大多数公司是不喜欢这种不能“循规”按点来上班的员工，加上自己想要自由点，喜欢独处不喜欢和跟随群体节奏。那种你几点去吃饭，几点下班，这种按部就班的生活，会让我觉得自己束缚在一个框架。这种模式可能有他的好处吧，但是这种按点生活，有时候会打断开发思路，比如，我比较常遇到的事写代码写得很专注的时候，突然有个同事喊你说：吃饭了，这其实是很难受的。

所以，相对的自由职业更随心。想晚睡就晚睡，想晚起就晚起，随时随地想干啥干啥。时间完全由自己把控，非常自由。

可能大家会说自由职业是否有经济收入压力，我的答案：是有的。

一般来说自由职业可能大家会靠接外包，网站上找单子来做。我这边的话，主要是靠朋友介绍，相对来讲比较靠谱。像是之前，我在一个 Flutter 群里看到有人问有没有人接 UI 改造的活，我去了解了下它的产品，感觉并不是很靠谱就放弃了。所以，相对而言，朋友介绍会更靠谱点，无论是甲方还是开发内容。

就像很多人说的，自由职业没有相对稳定的收入，也许什么时候我就结束自由职业的生活。因为现在我虽然会接一些有收入的外包项目来做，但是很多时候其实我是依据自己的兴趣在落地自己的一些想法，开源出来一些自己的项目。但这些是没有经济收入的，全靠兴趣在支撑着。

# 自由的时间，做想做的事情

整个自由职业的过程中，其实我主要是做一些自己感兴趣的事情。像是之前社区 [《Springboot 撞上 NebulaGraph——NgBatis 初体验》](https://discuss.nebula-graph.com.cn/t/topic/12548) 提到的 NgBatis，就是比较代表的一个项目。

这个项目起源于一个自己想用 NebulaGraph 当业务数据库来落地的应用。那时候，手头上刚好有一个连接其他图数据库的半成品，因为 ClassLoader 的原因，没办法通过 `java -jar` 项目包.jar 的方式来启动应用，这对于 Spring Boot 的应用可以说是致命的，不得不搁置。但前面有提过，我开启了自由职业模式，有了自由的时间之后，刚好又有使用的契机，就想着再做次努力，没想到最后把之前碰到的困难攻克了，也因此进到了 NebulaGraph 社区。

在进社区之前还有个小插曲，Nebula 社群之前进群申请是需要和公司信息挂钩的（当然现在不需要了，由于当时没有归属公司的缘故，我的进群申请没通过。因为后来的 NgBatis 才破格进的群。进群后，通过运营的介绍得知已经有了一个 ORM 的框架 [graph-ocean](https://github.com/nebula-contrib/graph-ocean)，也因此认识了朝来老师以及很多像朝来老师这样热心开源的开发者。如果你习惯用 JPA 的方式，graph-ocean 也是个很不错的选择。

而在 NgBatis 之前我还有另一个 Flutter 的 UI 组件库的项目，就想着能不能结合 NebulaGraph 做一个桌面应用性质的客户端，可以用来直观地操作图数据库，于是就有了 [GraphDesk](https://www.dudu.ltd/products/graph-desk)（产品还有些缺陷，如果你在使用过程中遇到问题，欢迎轻拍反馈）。在做 GraphDesk 的过程当中，一些生态化的问题就浮出了水面。相比其他语言健全的生态，Dart 语言的生态相对薄弱，比如说数据可视化，比如说市面上的数据库几乎很难找到 Dart 语言的驱动程序，更不用说还处在成长期的图数据库，可自己偏偏很看好这两个方向，也刚好有时间为自己所看好的方向做点事。可以说程序员是一个单纯而不乏勇气的群体，既然碰到问题，那就直面问题，最后解决问题，所以有了后来的 flutter_graph_view 解决 Dart 生态中图数据可视化问题，跟 nebula_dart_gdbc 解决 NebulaGraph 的 Dart 驱动问题。不过，目前阶段这些还都只是可用而已，离稳定、可靠还需要更多的测试，比如说现在正在使用 nebula_dart_gdbc 对前面提到的 GraphDesk 做全面的功能升级跟 UI 改造，因为很大概率会覆盖到移动端，于是 GraphDesk 也更名为 Star Shadow 星影，争取在自己更多的使用当中完善这些开源项目。

# 工欲善其事必先利其器

上面说了那么多，听运营小姐姐说专访快结束的时候，惯例是会在文末安利能提升生活幸福度和工作效率的小工具。

那，我就来介绍下 2 个我自己平时开发上觉得还不错的工具。

[Snipaste](https://zh.snipaste.com/)，一款截图软件，对于前端开发人员来说，应该会很实用，一边比对截下来的设计稿一边开发。在没有分屏的情况下，便捷程度会更明显。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/snipaste-dy.png)

另一个是 [MasterGo](https://mastergo.com/)，对于平时需要画画原型设计稿的开发人员来说挺友好的。既不需要写代码实现运行效果，又能在软件中及时预览到实际开发完的效果，还能自动标注生成样式。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/mastergo-dy.png)

安利完两款产品，回头一看，希望有一天鄙人做的 [NgBatis](https://github.com/nebula-contrib/ngbatis) 也能变成一款被人安利的产品，社区有小伙伴愿意的话，一起来共建下这个项目 :D

---

以上，就是社区用户大叶的自白。虽然你可能不曾了解他，但是如果你作为一个 Java、开源爱好者，不妨去用用他的作品：[NgBatis](https://github.com/nebula-contrib/ngbatis)，也许通过代码会让你更加了解这个人。


跨专业、个人独立开发者、“秒回” GitHub 用户 issue…大叶身上的任何一个标签都足以让他人记住他。这次我想借助这次专访的机会，让社区的小伙伴近距离地认识这位社区用户。

一名跨行转码到自由职业者的程序员自白 ｜ nStar 专访

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/kb-banner.png)

像是 NebulaGraph 这类基础设施上云，通用的方法一般是将线下物理机替换成云端的虚拟资源，依托各大云服务厂商实现“服务上云”。但还有一种选择，就是依托云数据基础设施，将数据库产品变成为云生态的一环，不只是提供自身的数据云服务，还能同其他的数据库一起分析挖掘业务数据价值。

在本篇分享中，让你在了解何为云原生基础设施之余，可以获得更多的 NebulaGraph 部署使用方法。又有新的使用姿势了，下面一起来了解下这个集成过程以及相关的使用方法。

# KubeBlocks 是什么

在介绍之前，可能有了解云生态的小伙伴，会好奇标题中的 “KubeBlocsk”是什么？它带有 Kube- 前缀，和云原生什么关系？

[KubeBlocks](https://kubeblocks.io/) 的名字源自 Kubernetes（K8s）和乐高积木（Blocks），致力于让 K8s 上的数据基础设施管理就像搭乐高积木一样，既高效又有趣。

它是基于 Kubernetes 的云原生数据基础设施，为用户提供了关系型数据库、NoSQL 数据库、向量数据库以及流计算系统的管理控制功能。

下面开始进入主菜，KubeBlocsk 对 NebulaGraph 的集成。别看本文篇幅不短，事实上集成过程非常便捷，三步就能完成本次集成实践。

# KubeBlocks 快速集成图数据库 NebulaGraph

因为本身 KubeBlocks 是 K8s 生态的框架基础设施，因此，你如果要基于 KubeBlocks 集成数据库或者是计算引擎的话，本章节内容就是相关的分享。简单来说，只要你熟悉 K8s，不需要学习任何新概念，像下面这样，3 步就搞定一个数据库的集成。

如果你不想了解集成过程，可以跳过本章节，直接进入到下一个章节的使用部分，了解如何在 KubeBlocks 上使用数据库。

下面，讲述本次 NebulaGraph 的集成过程，虽然本文以 NebulaGraph 为例，但是集成过程是相似的，可以举一反三。

## 1. NebulaGraph 的服务架构

第一步，我们需要理解集群的组成，了解图数据库 NebulaGraph 的每个模块作用，以及其配置启动方式。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/kubeblocks-1.png)
 
图 1: Nebula Graph 的架构图（来源：https://github.com/vesoft-inc/nebula)

如上图所示，完整的 NebulaGraph 系统是由内核和周边工具组成，包括不限于 nebula-console、nebula-python、nebula-java 等客户端。而其中的内核 Core 部分主要由三大服务组成，分别是：

- Meta Service：由 nebula-metad 进程提供，负责元数据管理，例如 Schema 操作、集群管理和用户权限管理等。如果集群部署的话，多个 metad 之间通过 raft 保证数据一致性；
- Graph Service：由 nebula-graphd 进程提供，负责处理计算请求；
- Storage Service：由 nebula-storaged 进程提供，负责存储数据。

## 2. 创建集群模板

在这一步，定义下集群拓扑、配置和版本等信息。

KubeBlocks Addon 支持多种扩展方式，目前主流的扩展方式是 Helm。因此，这里采用 Helm 方式来搞定相关部署配置：

创建一个 NebulaGraph 的 Helm Chart，并增加以下模板文件：

- `clusterdefinition.yaml`：用来定义集群拓扑、组件配置和组件启动脚本。根据第一步的分析，我们知道 NebulaGraph 集群是一个多组件的形态，如果我们要正常使用图数据的话，需要用到 3 个内核组件，和 1 个客户端组件。因此，在这个文件中，组件配置中需要包括 4 个组件，后面使用实践部分会讲到，这里不做赘述；
- `clusterversion.yaml`：用来定义版本信息，例如：每个组件的 Docker Images。在本次实践中，支持的是 NebulaGraph  v3.5.0 版本。此外，一个 `clusterdefinition.yaml` 文件可以关联多个 `clusterversion.yaml` 文件。因此，后续即使 NebulaGraph 发布了新版本，我们只用添加新的 `clusterversion.yaml` 文件就好。

搞定模版后，来快速地在本地环境调试下 Helm Chart，来校验正确性。

## 3. 添加 Addon 配置

最后，只用再添加大约 30 行 YAML 代码，就可以将新添加的 NebulaGraph 配置为 KubeBlocks 的 addon，非常方便。

就这样，三个步骤，就完成了 KubeBlocks 对 NebulaGraph 的集成。

附上相关的 PR 方便你做参考，整个过程非常简单：

- [https://github.com/apecloud/kubeblocks/pull/3716](https://github.com/apecloud/kubeblocks/pull/3716)
- [https://github.com/apecloud/kubeblocks/pull/3944](https://github.com/apecloud/kubeblocks/pull/3944)

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/kubeblocks-2.png)

图 2. NebulaGraph Helm Chart PR

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/kubeblocks-3.png)

图 3. NebulaGraph Addon PR

当然，如果你想在 KubeBlocks 上集成其他数据，一统你的那些数据库们，可以参考上面的思路。按照官方说法：“目前 KubeBlocks 已经支持了非常丰富的数据库架构和部署形态，如 MySQL、Redis、MongoDB 等，包括多种使用主备复制架构和基于 Paxos/Raft 的分布式架构”。

下面，来说说如何在 KubeBlocks 上使用图数据库 NebulaGraph。

# 如何在 KubeBlocks 上使用 NebulaGraph

你可以通过以下方式在 KubeBlocks 上体验 NebulaGraph 集群。

## 1. 安装 kbcli 和 KubeBlocks

安装最新版的 kbcli 和 KubeBlocks，下面是参考文档：

- kbcli：[https://kubeblocks.io/docs/preview/user_docs/installation/install-kbcli](https://kubeblocks.io/docs/preview/user_docs/installation/install-kbcli)
- KubeBlocks：[https://kubeblocks.io/docs/preview/user_docs/installation/install-kubeblocks](https://kubeblocks.io/docs/preview/user_docs/installation/install-kubeblocks)

## 2. 激活 Addon

安装了最新版本的 KubeBlocks 后，可以看到 NebulaGraph 已经出现在 KubeBlocks 的 addon 列表中。

下面命令可以查看到所有的 addon：

```shell
kbcli addon list
```

执行之后，我们可以看到 nebula 已经出现在列表中，但是它的状态是 `Disabled`。为了有效地控制服务资源，KubeBlocks 默认不会激活相关 addon 服务，只激活了几个主流数据库。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/kubeblocks-4.png)

注： 如果在列表中，没有找到 nebula addon，请检查下你安装的软件版本，确保已安装新版本的 kbcli 和 KubeBlocks。

因为 nebula 服务处于未激活的状态，下面我们来激活下服务：

执行下面命令：

```shell
kbcli addon enable nebula
```

因为网络原因， 激活 Addon 可能需要一点时间， 可通过如下 `addon describe` 命令查看是否激活成功。

```shell
kbcli addon describe nebula
Name:               nebula
Description:        NebulaGraph is an Apache 2.0 licensed distributed graph database.
Labels:             kubeblocks.io/provider=community
Type:               Helm
Status:             Enabled
Auto-install:       false
```

若状态显示 `Enabled` 则表示服务已经激活成功。

## 3. 创建 NebulaGraph 集群

1. 创建 NebulaGraph 集群

激活我们的 nebula 服务后，我们可以像创建 MySQL、PostgreSQL 集群一样，快速创建一个 NebulaGraph 集群，这里我们管它叫“mynebula”。像下面一样，一行命令搞定集群创建：

```shell
kbcli cluster create mynebula --cluster-definition nebula
```

其中：

- `mynebula` 是集群名称， 可以替换为你想要的集群名。
- `--cluster-definition` 指定了从哪个预定义的集群模板开始创建，我们选择 nebula。

2. 查看集群的各个组件

`list-components` 命令可查看集群的组件信息：

```shell
kbcli cluster list-components mynebula
```

这是执行结果：

```shell
 NAME              NAMESPACE   CLUSTER    TYPE              IMAGE
nebula-console    default     mynebula   nebula-console    docker.io/vesoft/nebula-storaged:v3.5.0
nebula-graphd     default     mynebula   nebula-graphd     docker.io/vesoft/nebula-storaged:v3.5.0
nebula-metad      default     mynebula   nebula-metad      docker.io/vesoft/nebula-storaged:v3.5.0
nebula-storaged   default     mynebula   nebula-storaged   docker.io/vesoft/nebula-storaged:v3.5.0
```

可以看到，一个完整的 NebulaGraph 集群由 4 个组件组成，包括 nebula-console、nebula-graphd、nebula-metad、和 nebula-storaged，这也和前文介绍的 NebulaGraph 服务架构相呼应。

3. 查看集群的各个实例

`list-instances`  命令用来查看实例信息：

```shell
kbcli cluster list-instances mynebula
```

可以看到，每个组件各自有多少实例，每个实例是什么配置规格。

```shell
NAME                                       NAMESPACE   CLUSTER    COMPONENT         STATUS    ROLE     ACCESSMODE   AZ       CPU(REQUEST/LIMIT)   MEMORY(REQUEST/LIMIT)   STORAGE     NODE                            CREATED-TIME
mynebula-nebula-console-65844d578b-vf9kz   default     mynebula   nebula-console    Running   <none>   <none>       <none>   1 / 1                1Gi / 1Gi               data:20Gi   kind-control-plane/172.19.0.2   Jul 09,2023 17:03 UTC+0800
mynebula-nebula-graphd-0                   default     mynebula   nebula-graphd     Running   <none>   <none>       <none>   1 / 1                1Gi / 1Gi               data:20Gi   kind-control-plane/172.19.0.2   Jul 09,2023 17:03 UTC+0800
mynebula-nebula-metad-0                    default     mynebula   nebula-metad      Running   <none>   <none>       <none>   1 / 1                1Gi / 1Gi               data:20Gi   kind-control-plane/172.19.0.2   Jul 09,2023 17:03 UTC+0800
mynebula-nebula-storaged-0                 default     mynebula   nebula-storaged   Running   <none>   <none>       <none>   1 / 1                1Gi / 1Gi               data:20Gi   kind-control-plane/172.19.0.2   Jul 09,2023 17:03 UTC+0800
```

4. 查看集群状态

`list` 命令用来查看集群整体状态：

```shell
kbcli cluster list mynebula
NAME       NAMESPACE   CLUSTER-DEFINITION   VERSION         TERMINATION-POLICY   STATUS    CREATED-TIME
mynebula   default     nebula               nebula-v3.5.0   Delete               Running   Jul 09,2023 17:03 UTC+0800
```

若显示 Status 为 `Running`，表示集群已经创建成功并正在运行。

5. 连接集群后，就可以像其他部署方式一样正常使用 NebulaGraph 的图服务了。像用 `SHOW HOSTS` 命令，查看当前数据和分布状态：

```shell
kbcli cluster connect mynebula

Connect to instance mynebula-nebula-console-65844d578b-vf9kz

Welcome!

(root@nebula) [(none)]> SHOW HOSTS;
+------------------------------------------------------------------------------------------+------+----------+--------------+----------------------+------------------------+---------+
| Host                                                                                     | Port | Status   | Leader count | Leader distribution  | Partition distribution | Version |
+------------------------------------------------------------------------------------------+------+----------+--------------+----------------------+------------------------+---------+
| "mynebula-nebula-storaged-0.mynebula-nebula-storaged-headless.default.svc.cluster.local" | 9779 | "ONLINE" | 0            | "No valid partition" | "No valid partition"   | "3.5.0" |
+------------------------------------------------------------------------------------------+------+----------+--------------+----------------------+------------------------+---------+
Got 1 rows (time spent 7.119ms/9.574125ms)

Sun, 09 Jul 2023 08:53:00 UTC
```

至此，你已经能正常使用 NebulaGraph 服务了。进阶使用的话，可以参考官方的文档：[https://docs.nebula-graph.com.cn/3.5.0/](https://docs.nebula-graph.com.cn/3.5.0/)

4. 运维 Nebula Graph Cluster

当集群状态为 Running 后，你可以登录集群查看信息，并进行常见的运维操作，像是扩缩容、服务启停：`hscale`、`vscale`、`volume-expand`、`start`、`stop` 等操作。

下面，以水平扩缩容 `hscale` 为例，示范下对 NebulaGraph 集群的运维过程。

通过 kbcli 的`hscale` 命令，可以对集群的指定组件进行扩缩容。例如，将 `nebula-storaged` 组件扩展为 3 个节点：

```shell
kbcli cluster hscale mynebula --components nebula-storaged --replicas 3
```

通过 `kbcli cluster list mynebula` 命令再次查看集群状态，可以看到状态变更为 `HorizontalScaling`，说明它正在扩节点：

```shell
 NAME       NAMESPACE   CLUSTER-DEFINITION   VERSION         TERMINATION-POLICY   STATUS              CREATED-TIME
mynebula   default     nebula               nebula-v3.5.0   Delete               HorizontalScaling   Jul 09,2023 17:03 UTC+0800
```

等待几十秒后，扩容成功。我们再来查看下实例信息，可以看到已经有 3 个 nebula-storaged 节点：

```shell
 kbcli cluster list-instances mynebula
 
 NAME                                       NAMESPACE   CLUSTER    COMPONENT         STATUS    ROLE     ACCESSMODE   AZ       CPU(REQUEST/LIMIT)   MEMORY(REQUEST/LIMIT)   STORAGE     NODE                            CREATED-TIME
mynebula-nebula-console-65844d578b-vf9kz   default     mynebula   nebula-console    Running   <none>   <none>       <none>   1 / 1                1Gi / 1Gi               data:20Gi   kind-control-plane/172.19.0.2   Jul 09,2023 17:03 UTC+0800
mynebula-nebula-graphd-0                   default     mynebula   nebula-graphd     Running   <none>   <none>       <none>   1 / 1                1Gi / 1Gi               data:20Gi   kind-control-plane/172.19.0.2   Jul 09,2023 17:03 UTC+0800
mynebula-nebula-metad-0                    default     mynebula   nebula-metad      Running   <none>   <none>       <none>   1 / 1                1Gi / 1Gi               data:20Gi   kind-control-plane/172.19.0.2   Jul 09,2023 17:03 UTC+0800
mynebula-nebula-storaged-0                 default     mynebula   nebula-storaged   Running   <none>   <none>       <none>   1 / 1                1Gi / 1Gi               data:20Gi   kind-control-plane/172.19.0.2   Jul 09,2023 17:03 UTC+0800
mynebula-nebula-storaged-1                 default     mynebula   nebula-storaged   Running   <none>   <none>       <none>   1 / 1                1Gi / 1Gi               data:20Gi   kind-control-plane/172.19.0.2   Jul 09,2023 17:46 UTC+0800
mynebula-nebula-storaged-2                 default     mynebula   nebula-storaged   Running   <none>   <none>       <none>   1 / 1                1Gi / 1Gi               data:20Gi   kind-control-plane/172.19.0.2   Jul 09,2023 17:47 UTC+0800
```

再次连接 NebulaGraph 集群，查看存储节点信息，可以看到新增的两个节点也已经可用，状态为 `online`：

```shell
kbcli cluster connect mynebula
Connect to instance mynebula-nebula-console-65844d578b-vf9kz

Welcome!

(root@nebula) [(none)]> SHOW HOSTS
+------------------------------------------------------------------------------------------+------+----------+--------------+----------------------+------------------------+---------+
| Host                                                                                     | Port | Status   | Leader count | Leader distribution  | Partition distribution | Version |
+------------------------------------------------------------------------------------------+------+----------+--------------+----------------------+------------------------+---------+
| "mynebula-nebula-storaged-0.mynebula-nebula-storaged-headless.default.svc.cluster.local" | 9779 | "ONLINE" | 0            | "No valid partition" | "No valid partition"   | "3.5.0" |
| "mynebula-nebula-storaged-1.mynebula-nebula-storaged-headless.default.svc.cluster.local" | 9779 | "ONLINE" | 0            | "No valid partition" | "No valid partition"   | "3.5.0" |
| "mynebula-nebula-storaged-2.mynebula-nebula-storaged-headless.default.svc.cluster.local" | 9779 | "ONLINE" | 0            | "No valid partition" | "No valid partition"   | "3.5.0" |
+------------------------------------------------------------------------------------------+------+----------+--------------+----------------------+------------------------+---------+
Got 3 rows (time spent 1.971ms/5.443458ms)

Sun, 09 Jul 2023 10:00:06 UTC
```

后续，我们还会逐步集成 NebulaGraph 的备份/恢复、监控、参数变更等能力。

如果你想要了解更多 kbcli 支持的运维命令，可翻阅文档：[https://kubeblocks.io/docs/preview/user_docs/cli](https://kubeblocks.io/docs/preview/user_docs/cli)。
 
# 丰富 NebulaGraph 生态

熟悉 NebulaGraph 周边生态的小伙伴，可能知道在 KubeBlocks 之前，NebulaGraph 对接了 Spark 和 Flink 生态，主要对接大数据生态，从而方便大家使用大数据的计算引擎。而这次，NebulaGraph 往云原生这边迈了一步，通过在 KubeBlocks 的集成，希望能给社区的大家带来更加丰富的生态环境。
正如本次完成集成工作的内核研发 [@xtcylist](https://github.com/xtcyclist) 所说：“用开源的方式解决开源的问题”，我们希望联合和上下游的开源生态，构建更完善的 NebulaGraph 图生态。而他同样认为“数据库全部容器化部署是大趋势；全部 K8s 化部署也是一个比较热的预言。”。

因此，拥抱未来，NebulaGraph 先在 KubeBlocks 上进行了集成工作。如果你想要加入，完善 NebulaGraph 的生态，欢迎留言交流你的看法。

---

**谢谢你读完本文** (///▽///)

欢迎前往 GitHub 来阅读 NebulaGraph 源码，或是尝试用它解决你的业务问题 yo~ GitHub 地址：[https://github.com/vesoft-inc/nebula](https://github.com/vesoft-inc/nebula) 想要交流图技术和其他想法，请前往论坛：https://discuss.nebula-graph.com.cn/

想要了解更多 KubeBlocks 和 NebulaGraph 的集成故事，欢迎来本周六的 meetup 同我们线下面对面交流~分享现场更有 NebulaGraph 绕坑秘籍放送 🧐 报名传送门：[https://3393206724443.huodongxing.com/event/1711136721400](https://3393206724443.huodongxing.com/event/1711136721400)

本文让你在了解何为云原生基础设施之余，可以获得更多的 NebulaGraph 部署使用方法。

云原生基础设施实践：NebulaGraph 的 KubeBlocks 集成故事

大家好，我是来自 BOSS直聘的赵俊南，主要负责安全方面的图存储相关工作。作为一个从 v1.x 用到 v3.x 版本的忠实用户，在见证 NebulaGraph 发展的同时，也和它一起成长。

# BOSS直聘和 NebulaGraph

关于 NebulaGraph 在 BOSS直聘的应用场景，大家可以看看之前文洲老师的文章（[图数据库 NebulaGraph 在 BOSS直聘的应用](https://discuss.nebula-graph.com.cn/t/topic/1870)），从那时候文洲老师构建的行为图发展到了安全场景的业务主图、算法推理图、职位相似度图谱等业务，现在更是支持了数仓同学的数据血缘及搜索同学的实时搜索召回场景，单图的规模达到了数千亿。 

在图计算方面，BOSS 直聘基于 LPA 和 Louvain 的单度团、多维团，以及基础的离线特征，在安全生产环境中广泛应用图技术。相信未来图在 BOSS直聘还会有更为宽广的舞台。

# UDF 的萌生

随着 NebulaGraph 在 BOSS直聘业务上的广泛应用，相对应的对内部技术人员的要求也越来越高。如果技术人员仅仅停留在使用层面，就无法满足从功能到性能很多需求。所以，学习源码成为了必然。

而后迁移 Neo4j->NebulaGraph 过程中，发现业务对 Neo4j 的 UDF 包有所依赖，我本萌生了实现 NebulaGraph UDF 功能的念头。

# UDF 设计和实现原理

![](https://www-cdn.nebula-graph.com.cn/nebula-blog/code-reading-qe-planner-arch.png)

上图是一条完整 nGQL 语句的执行过程，而 UDF 实现原理同 nGQL 的执行流程相关，大致如下：

graphd 接收到语句 -> Bison 词法解析（切词） -> Flex 语法解析创建 Sentence -> Validator 校验并生成AstContext（抽象语法树） -> toPlan 生成执行计划 Planner -> Optimizer 优化器优化 -> Executor 执行器执行。

在词法语法解析阶段，Function 会被单独解析出来。FunctionManager 作为原生的内置函数管理者，负责函数的定义、加载、调用等操作，从而管理函数的整个生命周期。调用语句通过 FunctionManager 查找到的函数最终会被执行器调用执行。

NebulaGraph 的 UDF 实现基于函数的调用执行流程，增加了 FunctionUdfManager：

```
static std::unordered_map<std::string, Value::Type> udfFunReturnType_;
static std::unordered_map<std::string, std::vector<std::vector<nebula::Value::Type>>>
    udfFunInputType_;
std::unordered_map<std::string, FunctionManager::FunctionAttributes> udfFunctions_;

class FunctionUdfManager {
 public:
  typedef GraphFunction *(create_f)();
  typedef void(destroy_f)(GraphFunction *);

  static StatusOr<Value::Type> getUdfReturnType(const std::string functionName,
                                                const std::vector<Value::Type> &argsType);

  static StatusOr<const FunctionManager::FunctionAttributes> loadUdfFunction(
      std::string functionName, size_t arity);

  static FunctionUdfManager &instance();

  FunctionUdfManager();

 private:
  static create_f *getGraphFunctionClass(void *func_handle);
  static destroy_f *deleteGraphFunctionClass(void *func_handle);

  void addSoUdfFunction(char *funName, const char *soPath, size_t i, size_t i1, bool b);
  void initAndLoadSoFunction();
};
```

它主要做以下几件事：

1. 和 FunctionManager 一起初始化，initAndLoadSoFunction 开启定时扫描，扫描 `--udf_path` 路径下文件；
2. loadUdfFunction加载 `.so` 文件，实例化函数方法，以函数名为 key 保存在 Map 中；
3. 在启用 UDF 功能的情况下，FunctionManager 未查找函数时，查找并调用 FunctionUdfManager Map 中的函数。

实现比较简单，可以说是取巧了，有需要的话 UDAF 也可用类似方式实现。

# UDF 使用方法

下面来讲讲 NebulaGraph UDF 的具体使用，如果你是用 NebulaGraph v3.5.0+ 版本的话，就可以按照以下方式使用 UDF 功能了。如果你是 v3.4.x 及以下版本，UDF 功能是暂不支持的，你也可以 cherry-pick 这个 [pr](https://github.com/vesoft-inc/nebula/pull/4804) 自行编译使用 UDF 功能。

第一步，在 graphd 配置文件中开启 UDF 功能并指定包目录

```shell
# enable udf, c++ only
--enable_udf=true
# set the directory where the .so of udf are stored
--udf_path=/home/foobar/dev/nebula/udf/
```

第二步，编写自定义函数代码，继承 GraphFunction。GraphFunction 的结构如下：

```
class GraphFunction;

extern "C" GraphFunction *create();
extern "C" void destroy(GraphFunction *function);

class GraphFunction {
 public:
  virtual ~GraphFunction() = default;

  virtual char *name() = 0;

  virtual std::vector<std::vector<nebula::Value::Type>> inputType() = 0;

  virtual nebula::Value::Type returnType() = 0;

  virtual size_t minArity() = 0;

  virtual size_t maxArity() = 0;

  virtual bool isPure() = 0;

  virtual nebula::Value body(
      const std::vector<std::reference_wrapper<const nebula::Value>> &args) = 0;
};
```

* create、destroy 是函数的创建销毁方法；
* name 调用时的函数名；
* inputType、returnType 输入输出类型；
* minArity、maxArity 参数数量；
* isPure 函数是否有状态；
* body 函数的实现。

第三步，编写好的函数打包成(.so)文件，放到配置文件 `--udf_path` 配置的对应目录下，graphd 服务会定时（5 分钟）扫描该路径下的包，加载到函数库中。之后，就可以在自己的语句中调用对应的函数了。

⚠️ 注意：由于 graphd 只扫描本地路径下的函数包，想让多个 graphd 都生效，必须都在本地路径下有相应的包。

这里要 cue 下思为老师，感谢他补充的完整使用文档和编译环境：[https://github.com/vesoft-inc/nebula/pull/4804](https://github.com/vesoft-inc/nebula/pull/4804) 。

# UDF 尚未解决的问题

虽然目前 UDF 是能用，但是它还存在部分优化问题。比如：

1. so 包位置只支持扫描本地；
2. 函数只在 graphd 层，无法下推到存储；
3. 使用麻烦，需要用户编码。

当然这些问题和一开始的设计息息相关：开发 UDF 之初，其实是想兼容 C++ 的 so 包和 Java 的 jar 包，但测试了 C++ Jni 调用 Java 的性能，发现基本上无法用于大规模的生产。

下图便是当时的性能测试：

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/udf-benchmark.png)

因为实现实在是性能堪忧，于是就放弃了一开始的设计。

当然还有一些未来规划上的事情，主要是希望 NebulaGraph 开发团队一起合作完成：

1. 个别的大查询语句和深度查询，容易把 storaged 的内存打满影响集群整体性能。是否可以考虑通过查询时间超时或内存监控自动 kill 对应的查询，释放掉内存。其实对于类似的语句，基本上已经很难拿到结果了，更多的可能是想降低语句带来的影响
2. 集群的容错性，多副本情况下某个节点的非正常下线会影响整体集群，由于环境的复杂性具体定位分析也比较困难，盼望尽可能增强集群健壮性。

# 开发 UDF 的意外收获

前面说过，UDF 其实是阅读 NebulaGraph 源码的产物。这里我想谈谈我对源码阅读感受：整体的 NebulaGraph 源码给我最直观的感受就是层次、结构清晰，代码优雅。在配合官方博客提供的内核讲解系列文章，对我这种跨语言学习的选手难度都大大降低了。

希望 UDF 能帮你解决一些问题，以及我的分享能给你带来一丝启发。


本文来自 BOSS 直聘的赵俊南，作为一个从 v1.x 用到 v3.x 版本的忠实用户，在见证 NebulaGraph 发展的同时也和它一起成长的故事。

NebulaGraph UDF 功能的设计与背后的思考

![](https://www-cdn.nebula-graph.com.cn/nebula-website-5.0/images/blogs/%E4%BA%BA%E7%89%A9%E4%B8%93%E8%AE%BF_%E7%94%BB%E6%9D%BF%201%20%E5%89%AF%E6%9C%AC%202.jpg)

同为程序员的你，可能见过“代码写诗”来形容一个人的代码优雅程度。而本期的 nStar 专访嘉宾——储惠龙，是一个文学爱好者，个人博客的「我的诗与短句」记录着美好的青鸟。虽然现在从事同文学几乎无关的编程工作，其实他的对文学、优雅的热爱多了一种表达方式：代码。

虽然毕业未满 1 年，全职工作的他在 8 个月实现了快速的迭代。在成长过程中，他接触到了开源项目，慢慢地明白开源是什么，也有了自己的开源项目。

这就是开源项目 NebulaResultSetBoot 和 NebulaGraphQL 的作者——储惠龙。

# 优雅的小龙人

```C++
int main() {
// 储惠龙
string name = "储惠龙";
string githubId = "https://github.com/Dragonchu";
string base = "Beijing";
string jobDescription = "京东科技-风控团队";
 
return 0;
}
```

## 我是小龙人

清蒸：**来，和社区的大家打个招呼**。

储惠龙（以下简称：小龙人）：大家好，我叫储惠龙，大家可以叫我小龙人。我是本科从中南大学毕业。对，去年刚毕业。目前在京东科技风控这边工作，刚刚上班满 8 个月，所以还有很多需要学习和进步的地方。

平时呢，我比较喜欢科技相关的事，写写代码，做下工程。还有一些特殊的爱好，就是会写点技术文章和诗歌短句。和大家差不多，空闲的时候也会玩玩电子游戏、桌游之类。

## 文学和我

清蒸：**在你的[个人博客](https://dragonchu.github.io/index.html) 中，单独有一个分类是「诗和短句」，你是怎么喜欢上诗歌的呢**？

小龙人：高中的时候，有个语文老师说：年轻人就应该写点这些东西（这里指的是诗歌）。算是一个契机吧，从那以后我就开始用这个方式来记录一些事情。不过，我律诗绝句写得比较少，一般就写写现代诗。

清蒸：**那你平时看得比较多的，是谁的现代诗呢**？

小龙人：我看海子的诗歌会多点。之前我也看过一本诗歌大杂烩，里面的诗歌太美了，我把它们都背了一遍。不过，这过去很久了。后来，看得就比较少。我还记得那本大杂烩中有一首歌，讲到“蓝色大蝴蝶”和“一群孩子在玩”，只不过我再也找不到这首诗是什么。如果，有小伙伴知道这是什么诗，麻烦告诉我下。

清蒸：**有人喜欢诗歌的美感，寥寥片语留下无穷遐想，你喜欢诗歌哪点呢**？

小龙人：只是因为诗歌“短”而已。诗歌也好，文章也罢，总的来说就是传递情感和故事。有的时候，你可能寥寥几个字，就已经把那些事讲完了。但有的时候就是想讲得含蓄一点，因为有的事情，你直白白地讲出来就没有意思了，所以诗歌会好点。假如你想把整个中间的过程都明明白白讲出来，就可以换个记录方式，这只是一个取材问题。

## 话剧和我

清蒸：**好像你之前还在话剧团待过？本科读的是计算机，为啥会去参加话剧社呢**？

小龙人：对，大学我加入过话剧社团，还是个团长。那时候，就单纯觉得好玩，觉得上了大学应该多去体会不一样的东西。在这个过程中接触了一些剧本编写、舞台搭建、会务相关的事情，还是挺好玩的，有了不一样的体验。

# 快速成长的小龙人

## 在社区中成长

清蒸：**之前你说到过，毕业工作的这 8 个月，是一个快速成长的过程。我觉得人的成长和他接触的东西，或者是做的事情息息相关。所以，你身上发生了什么故事呢**？

小龙人：（狗头）这里真的要好好感谢 NebulaGraph 社区了。其实，我之前一直很想接触开源社区，但是确实很难。因为，很多社区的入门门槛会很高，特别是你如果小白一点，压根进不去。

NebulaGraph 这边用了比较本土化的沟通方式——微信群，和 Apache 倡导的 Email 的方式不大一样。微信群这种方式更符合我的实际情况，而且在群里看各位大佬讨论问题，即便我不发言，在这个过程中我也学到了不少东西。当我学到一些东西的时候，又反向去帮助别人，这种向他人学习、帮助其他群友的过程，收获到了很多东西。尤其是思为大佬，帮助了我很多。

简单来说，跟在大家后面学习，即便不交流，潜移默化也获得了很多知识。

## 在成长中输出

清蒸：**其实，你在这个过程中也开源了自己的两款产品： NebulaResultSetBoot 和 NebulaGraphQL。它们是你的工作产出么**？

小龙人：[NebulaResultSetBoot](https://github.com/nebula-contrib/NebulaResultSetBoot) 可能还算和工作有点关系，它是一个帮你把 Java 结果处理成 JSON 的小工具，在我的工作中的的确确会用到它。因为其实它是一个工程问题，相信很多 Nebula 小伙伴都遇到这个通信问题，我也不例外，所以当我解决了这个问题之后，就把它开源出来捐献给了社区。

但是，另外一款 [NebulaGraphQL](https://github.com/nebula-contrib/NebulaGraphQL) 就完全是一个兴趣的产物。那时候，我在一个群里看有群有提了一嘴 GraphQL，我就去查了下 GraphQL 是什么东西。然后我感觉这个东西还是挺好玩的，就花了自己的时间去做了一下。

其实做的过程也是想说学习，看能不能把之前的一些想法、一些学习到的东西都用一下。这两个项目其实也没花多久时间，可能就几个周末就完成了，但是这个开发的过程中的确自己也学到了不少东西。

清蒸：**这两款开源产品的未来，你有什么规划呢**？

小龙人：NebulaResultSetBoot 基本上是个完成品了，后续可发展的空间比较小。但是，NebulaGraphQL 还是大有可为的。

目前来说，NebulaGraphQL 只提供了查询点，这个很基础的功能。现阶段的它相当于是 MVP，就是最小原型，验证了整个方案的可行性，并且把流程串通了。

后续的规划，最大的一点就是把整个 GraphQL 那套查询都搬过来。同时，能在应用层做一些缓存的话，估计就直接起飞了。

再者，如果加上前端这块的话，NebulaGraphQL 就真的能实现质的飞跃。因为，GraphQL 是有两个方面可以做的应用，第一个是真正的将它作为一种生产力。不过，目前国内大部分公司用 RESTful 的比 GraphQL 多很多。要相关从业人员改用 GraphQL 还是有点成本的，而且也非必要，一般公司不会那么干。

即便如此，NebulaGraphQL 的工具属性还是点满的。尤其是对部分前端工程师，或者不熟悉Cypher 的工程师，想简简单单查看一下图数据库里面数据，即便 nGQL 再简单，还是有一定的上手难度的。如果用 GraphQL 提供一个可视化的查询界面，快速地去查询自己需要的数据，做下逻辑上的验证，还是不错的。

因此，我觉得 NebulaGraphQL 大概率往后的发展就是辅助工具。因为有了它，做可视化真的非常简便，数据库同前端的交互就太方便了。

# 不一样的小龙人

## 开源是一种互联网精神

清蒸：**上面你有提到过开源社区，你是咋理解开源的呢**？

小龙人：我觉得开源是最能体现早期的互联网精神，它也绝对不是一个无私的贡献。可能国内有些公司当一种商业策略，采用先开源获取一波用户之后再闭源。但其实，我觉得它更多的是一个互帮互助的过程。大家在你这个项目中学习到东西，再反哺给社区，是一个良心的循环。

## AI 能辅助工作和学习

清蒸：**你有用什么 AI 工具么？觉得用的感觉如何**？

小龙人：GPT 那套我用得比较多。一般，我知道整件事应该怎么做，明确地知道要做什么，但是我不想写那些代码，我就会直接让 GPT 帮我生成，完了之后调试一番。

如果是有指定的编码风格的话，像是用 Java 写代码，我可能还会指定一下它要用到什么流或者是库，不要用哪些工具之类的。这样稍微限制一下，编码风格会好很多。但是一般来说，常用的还是代码片段，代码片段其实风格都差不多。毕竟，现阶段让 GPT 直接写项目还是有点吃力的。

当然你足够有耐心，写很详细的 prompt，它的代码完成度就会非常高。但是写详细的 prompt 所需的时间也是相对应地增加，也许那个时间你直接自己写代码都写出来了。

不过，个人觉得它作为辅助工具，偷偷懒，解决一些不想写的代码片段还是不错的。

除了这点，AI 工具还有一个亮点是大大地降低学习成本，特别像是那些文档不全的项目。之前我就遇到过一次，压根没文档。但是我又需要去用它提供的工具，然后就打开 GPT 疯狂输入，向它提问。这极大地降低了我的学习成本。

## 安利时间

清蒸：**你觉得有什么好用的工具推荐给大家的么**？

小龙人：我日常用的比较多的可能是 Notion。它整个的设计非常的棒，用来处理我日常的文章记录挺不错。此外，Notion 的跨平台体验做得非常好，无论手机，还是浏览器，任何一个平台，你上去就能用，非常方便。

一起来看看开源少年的成长之路。

储惠龙：在 NebulaGraph 社区中快速自我迭代、成长的小龙人

本文详细地记录了使用 K8s 部署分布式图数据库 NebulaGraph 的过程。