**一、简介**

NebulaGraph 是一款开源的、分布式的、易扩展的原生图数据库，能够承载包含数千亿个点和数万亿条边的超大规模数据集，并且提供毫秒级查询。

图数据库在许多业务场景中扮演着重要角色，得益于其独特的数据模型和高效的查询性能。以下是一些常见的图数据库业务应用场景：

-   知识图谱：企业和组织需要从各种数据孤岛中构建领域知识图谱，支持智能问答和语义搜索。
    
-   社交网络分析：社交网络平台需要分析用户之间的关系、兴趣、互动等信息，以提供个性化推荐、广告定向投放。
    
-   金融风控：金融机构需要监测异常交易活动、识别潜在的欺诈行为、评估信用风险。
    
-   推荐系统：电子商务、媒体平台需要根据用户的浏览历史、购买记录等信息，提供个性化的商品或内容推荐。
    

NebulaGraph Cloud 是为 NebulaGraph 设计的全托管云服务，**本文将结合亚马逊云科技的产品，详细介绍如何实现降本增效。**


**二、NebulaGraph Cloud**

**平台架构**

![image|561x499](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/9da20f7acfd239dc38ee3ecc5f3bd1be4ceac701_2_561x499.jpeg)

NebulaGraph Cloud 基于 K8S 设计和构建 ，背后有以下因素：

-   K8S 的 Opertor 模式使得集群内部发生的一切可以被自动化，降低开发成本。
    
-   K8S 提供了一系列抽象能力，用于简化计算、存储和网络资源的管理，可以帮助用户避险厂商锁定，做到 100% Cloud agnostic。
    
-   K8S 内置的扩缩容、调度框架、资源监控、服务发现等能力，可以将各种管理操作变的更容易。
    

**服务组件**

NebulaGraph Cloud 由两部分构成：

**控制平面（Control Plane）**

提供用户控制台访问，包括组织管理、用户权限控制、数据库管理、网络安全设置、监控、告警等功能，帮助用户管理他们的 NebulaGraph 集群。

**数据平面（Data Plane）**

接收控制平面下发的指令，包括资源调度、配置、版本更新、水平扩缩容、规格调整、备份和恢复、可观测性、计量等功能。

**成本优化设计**

以数据库的配置示例来说明：


```
apiVersion: apps.nebula-cloud.io/v1alpha1
kind: Database
metadata:
  name: db123456
  namespace: db123456
spec:
  provider: aws
  region: "us-east-2"
  k8sRef:
     name: "k8s-ml65nmjg"
     namespace: "k8s-ml65nmjg"
  tier: standard
  graphInstanceType: NG.C4.M32.D0
  graphNodes: 1
  StorageInstanceType: NG.C4.M32.D50
  StorageNodes: 1
  version: v3.8.2c
```


数据库实例使用 CRD Database 定义，它在数据平面的管理操作由控制器 database-controller 负责。

对于依赖的计算资源通过 CRD NodePool 定义，**NodePool 是对各个云厂商计算资源的抽象，在 Amazon EKS 中用于管理 NodeGroup。**

前文提到 NebulaGraph 是计算-存储分离的架构，所以一个数据库实例会对应两个 NodePool 对象。

```
# Graph 资源池
apiVersion: apps.nebula-cloud.io/v1alpha1
kind: NodePool
metadata:
  name: gnp-7d0b156e
  namespace: db123456
spec:
  databaseRef:
    name: db123456
    namespace: db123456
  instanceCount: 1
  instanceType: x
  k8sRef:
    name: k8s-ml65nmjg
    namespace: k8s-ml65nmjg
  labels:
    platform.nebula-cloud.io/database-name: db123456
    platform.nebula-cloud.io/graph-pool: db123456-f24a
  provider: aws
  region: us-east-2
  zoneIndex: 0
  
# Storage 资源池
apiVersion: apps.nebula-cloud.io/v1alpha1
kind: NodePool
metadata:
  name: snp-59e9cc63
  namespace: db123456
spec:
  databaseRef:
    name: db123456
    namespace: db123456
  instanceCount: 1
  instanceType: x
  k8sRef:
    name: k8s-ml65nmjg
    namespace: k8s-ml65nmjg
  labels:
    platform.nebula-cloud.io/database-name: db123456
    platform.nebula-cloud.io/Storage-pool: db123456-un6g
  provider: aws
  region: us-east-2
  zoneIndex: 0
```

**规格调整**

选择合适的实例规格对用户和服务商都是一个比预期更具挑战性的任务。用户通常不清楚他们需要多大的实例，例如，当用户的数据从100 GB 逐渐增长到 1 TB 时，他们可能不清楚这些数据在每个阶段需要多少 CPU 核心或多大内存。这就需要用户和 SA 共同努力来找出答案。

在使用全托管云服务时，我们提供实例规格调整功能，支持对 Query 节点或者 Storage 节点单独调整，以满足用户在成本控制和性能达标方面的需求。用户可以根据监控面板的历史曲线判断是否达到单节点处理瓶颈，同时云平台也会发出站内告警。

![image|690x225](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/f5f5f6a57a63973e531106af4a1391e834c63d09_2_690x225.png)


**水平扩缩容**

水平扩缩容支持对 Query 节点或者 Storage 节点单独调整。**Query 节点可视为无状态服务，在处理查询流量波动时可通过扩缩容来解决。**

Storage 节点负责存储图数据并提供读写能力，每个 Storage 节点上都分布一定数量的数据分片。每次进行扩缩容都会涉及数据迁移及数据分片再均衡，因此需要谨慎操作。

节点扩容前需要准备相应的计算资源，控制器 database-controller 会将当前期望的节点数下发给 infra-controller 触发 Amazon EKS 的 NodeGroup 扩容，这里我们**没有启用 CA 或者 Karpenter 有以下原因：**

-   扩缩容决策依赖于特定的集群条件和资源请求，如果这些条件没有得到满足，它可能不会执行预期的扩缩容操作。
    
-   跨可用区场景下无法保证指定区域的扩缩容。
    
-   基于 Pending Pod 的模式跟我们的业务系统无法紧密集成。
    
![image|690x216](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/753847db27e05d64ab3f647df0523610bdbbb87c_2_690x216.png)


**自动弹性伸缩**

通过自动扩容/缩容支持不同的工作负载是我们的一个重要目标。由于计算和存储是分离的，我们可以根据每个服务节点的利用率来增加或减少 CPU 和内存资源。

弹性伸缩服务架构如下：

![image|690x278](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/c8ff42ffa7adc0f30c46e9d1618dd8a09d92748b_2_690x278.jpeg)


每隔 10 分钟，弹性伸缩服务就会根据监控数据的历史和当前值计算数据库实例应分配的资源量，最终确定是否应增加或缩减计算资源。

**它可以驱动水平扩缩容和垂直扩缩容（调整实例规格），确保业务高峰时能提前弹出来。** 我们在此基础上将继续不断改进，通过纳入更多指标和主动预测策略来缩短扩缩容的时间。

**三、效率提升设计**

**网络安全访问**

![image|690x228](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/b49d9f8193e3bde0f05041a65507764da8955fea_2_690x228.png)


**目前我们为用户提供两种网络连接方式：网络白名单和 Privatelink 私网连接。**

为了确保网络安全并简化配置步骤，我们在数据库实例与网络负载均衡（NLB）之间引入了代理服务 ngproxy，充分利用了 NLB 提供的功能。NLB 支持在通过的每个报文上设置 PPv2 header，ngproxy通过解析报文可以知晓用户端的 endpoint ID 与在控制台设置的 ID 是否一致，不匹配则会拒绝请求。同样的原理也适用于公网访问的白名单，只有当源地址与白名单中的地址匹配时，才会被允许通过。

**备份和恢复**

**数据备份是防止数据丢失的第一道防线。** 无论是因为硬件故障、软件错误、数据损坏还是人为操作失误，备份都可以确保数据的安全。

我们为用户提供手动备份和定时备份两种方式，将备份数据上传到亚马逊云科技的对象存储Amazon S3。我们没有采用基于云存储快照的备份恢复方案，因为基于 SST 的备份恢复速度比云存储快照更快，而且不需要依赖云厂商的基础服务。需要注意的是，在进行数据备份时 DDL 和 DML 语句将会被阻塞，因此建议在业务低峰期执行备份操作。

备份数据目录结构：

```
backup_root_url/
- BACKUP_2024_08_20_16_31_43
├── BACKUP_2024_08_20_16_31_43.meta
├── data
│   └── 10.0.0.12:9779
│       └── data0
│           └── 5
│               ├── data
│               │   ├── 000009.sst
│               │   ├── 000011.sst
│               │   ├── 000013.sst
│               │   ├── CURRENT
│               │   ├── MANIFEST-000004
│               │   └── OPTIONS-000007
│               └── wal
│                   ├── 1
│                   │   ├── 0000000000000000001.wal
│                   │   └── 0000000000000000005.wal
.....
│                   ├── 30
│                   │   ├── 0000000000000000001.wal
│                   │   ├── 0000000000000000004.wal
│                   │   └── 0000000000000000005.wal
└── meta
    ├── __disk_parts__.sst
    ├── __edges__.sst
    ├── __id__.sst
    ├── __indexes__.sst
    ├── __index__.sst
    ├── __last_update_time__.sst
    ├── __local_id__.sst
    ├── __parts__.sst
    ├── __roles__.sst
    ├── __spaces__.sst
    └── __tags__.sst
- BACKUP_2024_08_20_19_02_35
```

恢复数据时采用恢复至新实例的方案，这样可以充分利用云上资源弹性扩展的优势，在指定某个时间点的备份集后快速拉起一个新的数据库实例，用户在验证新的数据库实例工作正常后可以释放掉旧实例。

**高可用性**

针对那些对服务可靠性要求极高的用户，我们提供了跨可用区容灾解决方案。

在 NebulaGraph 中 Zone 是服务节点的集合，它将多个 Storage 节点划分成可管理的逻辑区域，实现资源隔离。同时，平台服务会控制 Query 节点访问指定的 Zone 内的副本数据，从而降低跨可用区通信产生的网络延时与流量成本。

管理有状态服务跨可用区的一个主要挑战是存储卷的区域亲和性问题。为了解决这个问题，我们采取了在每个可用区放置一个 NodeGroup 的方法。这样一来，就可以避免新扩容的 Node 可能被错误地安排在不正确的可用区中，从而导致 Pod 无法被调度的情况发生。

根据过往用户案例中的经验，我们还支持在某个可用区单独扩容的方案。云原生社区类似 HPA 的方案，只解决了扩容后的数量问题，但是无法扩容到指定区域。根据每个区域承载的业务流量进行扩展，可以有效地提高服务质量。如果某个区域观察到 QPS 突然激增，数据平面的弹性伸缩服务将允许在此区域缩放 Query 节点。

![image|690x309](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/ead9f0ff2d6e68afb9a05dbdc2ec418e60590178_2_690x309.png)


**四、云上实战**

在开通订阅后开始创建数据库，接下来演示访问数据库的几种方式：

**可视化工具**

从 Database 列表选中某个实例，进入 Data->Graph 图空间管理，点击 Explorer Graph 进入可视化应用。

![image|690x198](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/ce7ed2c9cfab7106e383bd3424e40c8237588324_2_690x198.png)


点击右上角的 Console 打开控制台便可以执行 GQL 语句的查询。

![image|690x359](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/b097fa13dfc3ad0490e89138ee5c00e68c4d585f_2_690x359.png)


**网络白名单**

在数据库实例的 Overview 页面点击 Connect，选中 Public 方式。

![image|644x499](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/90dc038f3a3e9714718599fc876fdfead128eb83_2_644x499.jpeg)


在没有配置网络白名单时，数据库实例无法直接从公网访问。

```
$ ./nebula-console -addr nebula-graph-ncqqo19eh0aus73e4un6g.aws.cloud.nebula-graph.io -port 9669 -u dbaas-test@vesoft.com -p $PASSWORD -enable_ssl

Welcome!

(dbaas-test@vesoft.com@nebula) [(none)]> show spaces;
+------------------------+
| Name                   |
+------------------------+
| "genshin"              |
| "hanxiaotest"          |
| "movie_recommendation" |
| "nba"                  |
+------------------------+
Got 4 rows (time spent 602µs/222.883326ms)

Mon, 02 Sep 2024 16:52:39 CST
```


**Privatelink 私网连接**

按照 Create Private Link Endpoint 的配置步骤，确定业务所在的 VPC ID 和 Subnet ID。

运行命令创建 Endpoint：
```
aws ec2 create-vpc-endpoint --vpc-id <YOUR-VPC-ID>  --region us-east-2 --service-name com.amazonaws.vpce.us-east-2.vpce-svc-04f25889c855f891b --vpc-endpoint-type Interface --subnet-ids  <YOUR-SUBNET-IDs>
```

登录亚马逊云科技控制台查看 Endpoint 状态：

![image|690x212](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/1fe27de7e96f4deb53862da71dbcbbe02a8f6afb_2_690x212.png)


在业务 VPC 内测试访问是否正常。

![image|690x146](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/cb5260250eb6c4b416f9578ffa1d4106d5be1291_2_690x146.png)


接下来大家可以按照自己的业务需求通过官方生态工具在云上进行数据维护。

**五、总结与展望**

本文介绍了基于云原生理念在亚马逊云科技上的服务落地 NebulaGraph 全托管云服务的架构细节，**着重阐述如何通过亚马逊云科技的产品为用户带来实质利益，为用户在云端使用 NebulaGraph 提供兼具成本和弹性优势的全新解决方案。**

在确保服务质量的同时，我们将继续探索各种可能性，降低用户成本并提高易用度。我们的目标是让用户只需为其使用的资源付费，将成本概念贯彻到每一个细节中。

**目前 NebulaGraph Cloud Beta 版本试用活动正在火热进行中，** 每月最高消费控制在1美元以内，大家可以通过以[下链接注册账号](ttps://aws.amazon.com/marketplace/pp/prodview-wctboqxrwqkjy?sr=0-1&ref_=beagle&applicationId=AWSMPContessa) 或[直接访问注册账号](https://cloud.nebula-graph.io)。

欢迎对 **NebulaGraph Cloud** 感兴趣的小伙伴添加小助手 NebulaGraphbot(wechat) 解锁更多 DBaaS 相关内容。

只要1$ 解锁 NebulaGraph on AWS，通通1$

全托管 NebulaGraph 试用活动进行中！解锁成本优化与效率提升的实践指南


自 2023 年 8 月 **NebulaGraph** 和 **LlamaIndex** 共同推出 [Graph RAG](http://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247508410&idx=1&sn=a0432b3bbeac4e60a43c320f88201e81&chksm=cfe75b6ef890d278dedc9685b25459aa6bd7186ae06ea76f861f9c92964a4a0177cd1f818741&scene=21#wechat_redirect) 以来，凭借着 **LLM（大语言模型)**  和 **RAG（检索增强生成）** 的发展势头，在业界掀起了一场革命。通过本文，我们将向你介绍什么是 Graph RAG，为什么它具有革命性，以及如何构建你的Graph RAG，来利用数据的上下文与 NebulaGraph 回答复杂的多部分问题。

## 了解日益流行的 Graph RAG

Graph RAG 能够将知识图谱与大语言模型（LLM）结合使用，从而为搜索引擎提供更全面的上下文理解。由于其带来了更具成本效益、更智能且精确的搜索结果，这项技术已引起了广泛的关注。除了提供更准确的回答以建立用户信任外，Graph RAG 还克服了传统搜索增强技术的主要障碍：缺乏上下文理解和数据训练。因此，这些先进的检索增强技术有望扩展到各个行业，如医疗诊断辅助、内容创作和推荐、互动游戏以及知识图谱构建。

微软在由高级首席数据架构师 Jonathan Larson 和首席项目经理 Steven Truitt 撰写的博客文章《GraphRAG: Unlocking LLM Discovery on Narrative Private Data》中强调了 Graph RAG 的重要性。他们通过将 Graph RAG 与基线 RAG 系统进行对比，展示了 Graph RAG 的有效性，得出结论认为 Graph RAG 方法使LLM能够在图谱中找到支点，从而提供包含原始支持文本的更优答案。而基线 RAG 在处理需要跨数据集汇总信息以形成答案的查询时则显得力不从心。
**NebulaGraph 数据库已经集成了 LlamaIndex 和 LangChain 等大语言模型（LLM）框架** ；你只需专注于 LLM 编排逻辑和管道设计，无需担心复杂的实现。你可以通过简单的四个步骤进行试用，检查 Graph RAG 是否如传言般出色，然后再进一步将其集成到应用程序或其他场景中。

**注意：**

由于 LlamaIndex 的快速发展，最近的重构/重大变更导致一些 Graph RAG 教程无法运行。本文提供了更新后的 Graph RAG 教程，以便你可以无误地进行操作。

我们在上游发布之前已经探索了许多内部方法。我们相信 LlamaIndex 中Graph + RAG 的基本概念值得探索，因此我们将原始的工作坊和笔记本放在参考章节中。

**设置你的 NebulaGraph 集群**

* 通过 Google Colab 中的 NebulaGraph Lite 启动 NebulaGraph 集群
* 使用 Docker 扩展部署集群
* 实例化一个 NebulaGraphStore
## 使用 NebulaGrpah 构建你的 Graph RAG
~~~
import os
from llama_index.core import KnowledgeGraphIndex, SimpleDirectoryReader
from llama_index.core import StorageContext
from llama_index.graph_stores.nebula import NebulaGraphStore

os.environ["NEBULA_USER"] = "root"
os.environ["NEBULA_PASSWORD"] = "nebula"
os.environ["NEBULA_ADDRESS"] = "127.0.0.1:9669"


space_name = "paul_graham_essay"
edge_types, rel_prop_names = ["relationship"], ["relationship"]  # default, could be omit if create from an empty kg
tags = ["entity"]  # default, could be omit if create from an empty kg

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)
~~~
现在，随着你的 NebulaGraph 集群的设置，可以动手进行知识图谱构建部分。**请确保在 Jupyter 环境中运行以下所有步骤。**

**依赖关系**

Graph RAG 的实现需要以下依赖项：
~~~
pip install llama-index
pip install llama-index-llms-ollama
pip install llama-index-graph-stores-nebula
pip install ipython-ngql
pip install llama-index-embeddings-huggingface
~~~
**创建 LlamaIndex 知识图谱索引**

KnowledgeGraphIndex 可从非结构化文本中自动构建知识图谱，也可基于实体的查询。在创建图 RAG 查询引擎之前，你需要设置 LlamaIndex 知识图谱索引。在这个示例中，我们将演示如何通过创建文档对象来从文本数据构建知识图谱，然后再创建索引。
~~~
from llama_index.core import (
    VectorStoreIndex,
    SimpleDirectoryReader,
    KnowledgeGraphIndex,
)

graph_store.query("SHOW HOSTS")

Settings.chunk_size = 512

documents = SimpleDirectoryReader(
    "data"
).load_data()
~~~
~~~
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,
    max_knowledge_sequence=15,
)
~~~
### 创建一个朴素图 RAG 检索器

最后一步是创建 Graph RAG 检索器，在其基础上构建查询引擎，以便您可以使用自然语言问题进行查询。
~~~
from llama_index.core.query_engine import RetrieverQueryEngine
from llama_index.core.retrievers import KnowledgeGraphRAGRetriever

graph_rag_retriever = KnowledgeGraphRAGRetriever(
    storage_context=storage_context,
    verbose=True,
)

query_engine = RetrieverQueryEngine.from_args(
    graph_rag_retriever,
)
response = query_engine.query("What's the relationship between Bob and Alice")
~~~
现在，您已经尝试了 Graph RAG，如果您想进一步了解如何通过 GraphStore 和 VectorStore 进行检索，您可以在此处找到更多演示示例：https://www.siwei.io/tutors/GraphRAG/101.html。

[欢迎加入社区官方 Slack 群](https://join.slack.com/t/nebulagraph/shared_invite/zt-2h51ct4t0-IlXFaU01mpb3t2WgQ8qqNA)。

参考：

* https://bit.ly/graph-rag-workshop
* https://siwei.io/graph-enabled-llama-index/kg_and_vector_RAG.html
* https://siwei.io/demo-dumps/graph-rag/GraphRAG.html

通过本文，我们将向你介绍什么是 Graph RAG，为什么它具有革命性，以及如何构建你的Graph RAG，来利用数据的上下文与 NebulaGraph 回答复杂的多部分问题。

基于 NebulaGraph ，构建属于你的 Graph RAG 

![图数据库和知识图谱](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-28-1.jpg)

图数据库和知识图谱是管理图结构数据（包括节点（实体）和边（关系））的两大主流方案。图数据库利用基于图的数据模型存储信息，支持通过专用的图查询语言实现对图数据的查询和遍历；知识图谱通过整合推理和派生新知识的机制，增强了图数据库的功能。这种增强的表达力不仅让你能进行更高级的数据分析，还能从图中相互连接的数据点中提取洞察力。

本文将简要介绍知识图谱，再探讨使用 llamaindex 和 NebulaGraph-lite 生成知识图谱。

## 知识图谱是什么

知识图谱是一种图形化的知识表示方法，它将相关联的概念、事物及其关系描绘成一个网络。它涵盖了现实世界中的实体，如物体、人物、地点和事件。知识图谱的核心通常依赖图数据库，图数据库专注于通过存储离散的信息片段及其之间的关联来管理数据。

知识图谱的核心组成部分包括：**实体**是现实世界中的事物或概念，包括人、地点、活动和思想总结。在图型表达中，这是一种可视化数据集之间关系的方式，实体在图中表示为节点。

实体的例子包括：
- 人物：巴拉克·奥巴马、塞雷娜·威廉姆斯
- 地点/位置：纽约市、金字塔
- 事件：第二次世界大战、2008 年经济危机
- 抽象/意识形态：民主、重力

**关系**描述了对象之间的相互作用或联系方式，且展示了它们是如何联系在一起的。在知识图谱中，关系通过边来表示，这些边连接相应的节点。而边的流动方向可以是单向，也可以是双向，这取决于实体关系的性质。

### 知识图谱的分类

知识图谱拥有以下能力：
- 有效管理和可视化异构信息：能够在统一的框架内处理不同系统的数据，实现清晰且深具洞察力的信息展示。
- 集成新的数据资源：知识图谱固有的灵活性，能很好地同新数据源融合，支持知识库的持续扩充。
- 理解并阐释任何存储信息中的关系：能够发现并展示不同信息库中实体之间的关系，从而全面理解潜在的关联关系。

图谱的主要类型：

- RDF（资源描述框架）三元组存储：专注于存储和处理基于 RDF 框架的信息，该框架通过三元组（主体、谓语、客体）来表示知识。
带标签的属性图：专门研究节点和边附带信息标签的图，提供了更为丰富和细致的数据表现。

### RDF（资源描述框架）图

RDF 图，全称资源描述框架图，是用来表示类似网络结构的网络信息的一种方式。基本上，它是一系列围绕主题、谓词和客体组成的声明。以“巴黎是法国的首都”这句话为例，在 RDF 图中，“巴黎”作为主题，“是……的首都”作为谓词，“法国”作为对象（客体）。而这三个元素共同构成了一个“三元组”，代表了一个事实。一个 RDF 图可以包含众多这样的三元组，从而构建成一个互连的信息网络。 

资源描述框架（RDF）三元组存储是一种标准化的知识表示数据模型。在这个模型中，每个元素都通过统一资源标识符（URI）被赋予一个独一无二的标识符。这种机制确保主题、谓词和客体的机器可读性。此外，RDF 三元组存储采用了一种名为 SPARQL 的标准化查询语言，该语言支持从存储中检索数据。得益于数据表示和查询的标准化，RDF 三元组存储能够与其他遵循 RDF 框架的知识图谱实现互操作。

![SPARQL](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-28-2.png)

上图展示了一个社交网络中的个体（圆形节点 Jack、Joe、Jane），和他们之间的友谊关系（有向连接线 knows）。此外，每个有深色边缘的节点都表示该个体有收入（有向连接线 hasIncome）。菱形节点显示了网络中可能存在的额外数据（三元组）。

RDF 图的优点：

- 互操作性：RDF 是 W3C 的标准，意味着不同的系统可以理解并交换存储在 RDF 图中的数据。这使得它非常适合跨平台和应用程序之间的数据共享。

- 标准化：由于其标准化的格式，RDF 图支持标准查询语言 SPARQL 来探索和分析图中存储的数据。

- 推理与推导：RDF 图能够利用本体（可以视为对概念的正式描述）来进行数据推理。这使系统能够推导出图中没有直接表述的新信息。

- 灵活：RDF 图能够表述多种数据类型和关系，适合模拟复杂的领域和整合不同来源的数据。

### RDF 图的缺点：

- 深度搜索复杂：在大型 RDF 图中进行深度搜索的计算成本可能很高，这可能拖慢需要探索多个连接的查询的速度。

- 结构严格：RDF 数据以“三元组”（主体、谓语、客体）的形式存储，这种结构可能不如其他图模型那样灵活，后者允许对实体或关系本身添加属性。

- 学习曲线陡峭：理解和使用 RDF 需要良好地掌握其基本概念及 SPARQL 查询语言，这对新用户来说可能是一个挑战。

### 带标签的属性图 (LPG)

带标签的属性图（LPG）是一种用于表现具有相互连接的服务及其关系的特殊图数据库模型。以下是其主要特点的详细解释：

- 节点：可表示现实中的男性或女性特征。每个节点都具有独特的描述，并可被赋予一个或多个标签以表明其类型或大小（例如，“人物”、“产品”）。

- 属性：节点可能拥有键值对，用以存储关于该实体的额外信息。这些属性允许对图中的元素进行基本描述。

- 边：表示节点之间的联系，并展示实体间的关系。边与节点类似，可以用多种方式标记（例如，“认识”、“购买”），同时也可以拥有自己的属性。

LPG 的主要特性：

- 丰富的数据结构：节点和边都能拥有属性，与其他模型如 RDF 相比，允许更密集和信息量更大的数据表现。

- 高效的存储与查询：LPG 结构通常能带来高效的存储方式和更快速的图内连接遍历，便于进行查询。

- 灵活：LPG 由于没有预定义的模式，具备很高的灵活性，允许模拟多种数据关系。

### RDF vs 属性图

![RDF vs 属性图](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-28-3.png)

### 属性图与 LLM 模型结合的智能问答

属性图和大型语言模型（LLM）是两个强大的工具，可以结合使用，从数据中挖掘出新线索。以下是它们如何协作的具体方式：

**数据增强：dou bao z**

- LLM 可用于生成属性图中点和边的文本描述，这样不仅可以丰富数据内容，还能帮助其他工具或用户更加容易地理解各项关系。

- LLM 还可以基于图中已有的数据生成新的点和边，这对于进行异常检测或预测欺诈行为等任务非常有用。

**查询与探索：**

- LLM 可以用来创建查询属性图的自然语言接口，允许用户以比传统的图查询语言更为直观的方式（例如自然语言）对数据进行提问。

- LLM 也能够汇总图查询结果，并为这些发现生成解释。

**推理和推断：**

LLM 可以用于执行属性图上的推理任务，这可能包括基于现有数据推断节点间新的关系，或识别图中存在的不一致。

![LLM](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-28-4.png)

示例演示：

以下展示了使用 Llamaindex KnowledgeGraphIndex 和 NebulaGraph Lite Reference 结合 Google Gemini LLM 和 Collab 分步实现知识图谱的过程。

### 为 Gemini 生成 API 密钥

前往 https://aistudio.google.com/app/prompts/new_chat 并生成一个新的 API 密钥。

### 加载 PDF 文档

```
! mkdir ad && cd ad
! curl https://arxiv.org/pdf/2106.07178.pdf --output AD1.pdf
! mv *.pdf ad/
! pip install -q transformers

%pip install llama_index pyvis Ipython langchain pypdf  llama-index-llms-huggingface  llama-index-embeddings-langchain llama-index-embeddings-huggingface
%pip install --upgrade --quiet llama-index-llms-gemini  google-generativeai
%pip install --upgrade --quiet llama-index-graph-stores-nebula nebulagraph-lite
```

### 导入谷歌 API 密钥

```
import os

from google.colab import userdata
GOOGLE_API_KEY = userdata.get('GOOGLE_API_KEY')
os.environ["GOOGLE_API_KEY"] = GOOGLE_API_KE

```

### 导入必要的模块和库

```
import logging
import sys

logging.basicConfig(stream=sys.stdout, level=logging.INFO)
logging.getLogger().addHandler(logging.StreamHandler(stream=sys.stdout))
from llama_index.core import (
                         ServiceContext,
                         KnowledgeGraphIndex)
from llama_index.core import SimpleDirectoryReader
from llama_index.core.storage.storage_context import StorageContext
from pyvis.network import Network

from llama_index.llms.huggingface import HuggingFaceLLM
检查支持的 Gemini 模型。本例中，我们将使用 Gemini 1.0 专业版。

import google.generativeai as genai

for m in genai.list_models():
    if "generateContent" in m.supported_generation_methods:
        print(m.name)
        print(m)

from llama_index.llms.gemini import Gemini

llm = Gemini(model="models/gemini-1.0-pro-latest")

```
### 导入 BGE 嵌入

```
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.core import ServiceContext


embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-small-en-v1.5")

```

### 加载广告目录内容

```

documents = SimpleDirectoryReader("/content/ad").load_data()
print(len(documents))

```
###  在本地启动 Nebula 图数据库精简版的 Docker 实例

```
from nebulagraph_lite import nebulagraph_let
n = nebulagraph_let(debug=False)
n.start()

```

### 在 Nebula 存储中设置名为“nebula_ad”的命名空间和节点

```
%ngql --address 127.0.0.1 --port 9669 --user root --password nebula

# If not, create it with the following commands from NebulaGraph's console:
%ngql CREATE SPACE nebula_ad(vid_type=FIXED_STRING(256), partition_num=1, replica_factor=1)

```


```
import time

print("Waiting...")

# Delay for 10 seconds
time.sleep(10)

%ngql --address 127.0.0.1 --port 9669 --user root --password nebula
%ngql USE nebula_ad;
%ngql CREATE TAG entity(name string);
%ngql CREATE EDGE relationship(relationship string);

```
### 将文档数据加载到图数据库中

```
import os
os.environ["NEBULA_USER"] = "root"
os.environ["NEBULA_PASSWORD"] = "nebula"  # default is "nebula"
os.environ[
    "NEBULA_ADDRESS"
] = "127.0.0.1:9669"  # assumed we have NebulaGraph installed locally

space_name = "nebula_ad"
edge_types, rel_prop_names = ["relationship"], [
    "relationship"
]  # default, could be omit if create from an empty kg
tags = ["entity"]  # default, could be omit if create from an empty kg

from llama_index.core import StorageContext
from llama_index.graph_stores.nebula import NebulaGraphStore

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)

from llama_index.core import Settings

Settings.llm = llm
Settings.embed_model = embed_model
Settings.chunk_size = 512

```

### 更新图数据库中的节点数据


```

# NOTE: can take a while!
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,
    include_embeddings=True
)

```

### 检查 Nebula 存储中已插入的图数据

```

# Query some random Relationships with Cypher
%ngql USE nebula_ad;
%ngql MATCH ()-[e]->() RETURN e LIMIT 10

```

### 数据查询与输出：

![v](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-28-5.png)

### 现在开始查询索引数据

`query_engine = index.as_query_engine()`

```

from IPython.display import display, Markdown

response = query_engine.query(
    "Tell me about Anomaly?",
)
display(Markdown(f"<b>{response}</b>"))

```

**异常现象（Anomaly），在不同应用领域也可能被称作异常值、例外、特殊情况、稀有现象或新奇现象，它们指的是与常规、标准或预期显著不同的异常对象。**

```
from IPython.display import display, Markdown

response = query_engine.query(
    "What are graph anomolies?",
)
display(Markdown(f"<b>{response}</b>"))

```

图异常可以被定义为结构性异常。

## 小结

这些简单的知识图谱有效地捕捉了实体间的复杂关系，这种能力显著提高了查询和推理的精确性、多样性和复杂性。此外，这些知识图谱还可以扩展应用到基于 RDF 的复杂本体图。欢迎大家动手尝试～👏
参考：

[https://link.springer.com/chapter/10.1007/978-3-642-21295-6_13](https://link.springer.com/chapter/10.1007/978-3-642-21295-6_13)

[https://github.com/nebula-contrib/nebulagraph-lite](https://github.com/nebula-contrib/nebulagraph-lite)

[https://docs.llamaindex.ai/en/stable](https://docs.llamaindex.ai/en/stable)

本文由 Rajesh K 原文发布在 Medium

图数据库和知识图谱是管理图结构数据（包括节点（实体）和边（关系））的两大主流方案。图数据库利用基于图的数据模型存储信息，支持通过专用的图查询语言实现对图数据的查询和遍历；知识图谱通过整合推理和派生新知识的机制，增强了图数据库的功能。

基于 Gemini 和 NebulaGraph 构建知识图谱问答系统

![nebula-stats-exporter](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-1.jpg)

大家好，这里是玖叁叁，目前从事全栈工程师工作，刚刚接触 NebulaGraph 不久，还在努力学习当中。图数据库可以高效地表达、存储和分析复杂关系和网络，在特定场景下有着不错的性能。希望通过这篇 nebula-stats-exporter 的实践文章可以给各位读者朋友们一点启发。

### 01 关于 nebula-stats-exporter

nebula-stats-exporter 是一个 stats 接口转换工具，可以将 stats 接口返回的数据转换为Prometheus 可接受的数据格式，实现对 NebulaGraph 数据采集以及监控。

### 02部署环境说明

本篇文章将会对二进制部署以及 docker-compose 部署两种部署方式使用 nebula-stats-exporter 进行说明，均使用目前最新版本 v3.8.0

## 二进制部署

环境部署参考官方文档（https://docs.nebula-graph.com.cn/3.8.0/4.deployment-and-installation/2.compile-and-install-nebula-graph/2.install-nebula-graph-by-rpm-or-deb/），使用 RPM/DEB 的方式部署。

```
# 安装
sudo dpkg -i nebula-graph-3.8.0.ubuntu1804.amd64.deb

# 启动
sudo /usr/local/nebula/scripts/nebula.service start all

# 确认服务状态
$ sudo /usr/local/nebula/scripts/nebula.service status all

# 下载console工具，从下面的页面找对对应的版本下载
https://github.com/vesoft-inc/nebula-console/releases

# 重命名，并修改权限
mv nebula-console-linux-amd64-v3.8.0 nebula-console
chmod 755 nebula-console

# 使用console连接，注意实际上都是默认参数，直接使用./nebula-console就可以连接本地，不需要任何参数，密码默认为空
./nebula-console -addr <ip> -port <port> -u <username> -p <password>

# 注册 Storage 服务
ADD HOSTS 127.0.0.1:9779

# 安装完成，截图留念
```
![二进制部署](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-2.png)

```
# 测试三个服务的stats接口，
Meta：curl 127.0.0.1:19559/stats
Graph：curl 127.0.0.1:19669/stats
Storage：curl 127.0.0.1:19779/stats
```
## docker-compose 部署

环境部署参考官方文档，使用 docker-compose 部署
```
# 下载
git clone -b release-3.8 https://github.com/vesoft-inc/nebula-docker-compose.git

# 切换路径
cd nebula-docker-compose/

# 修改docker-compose.yaml，为了开启stats接口访问
修改内容如下
Meta服务三处
- 29559:19559
- 39559:19559
- 49559:19559
Graph服务三处
- 29669:19669
- 39669:19669
- 49669:19669
Storage服务三处
- 29779:19779
- 39779:19779
- 49779:19779

# 启动服务
docker-compose up -d

# docker部署无需手动添加Storage，使用console连接查看，服务正常
```
![Storage](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-3.png)

```
# 测试服务的stats接口，
Meta
curl 127.0.0.1:29559/stats
curl 127.0.0.1:39559/stats
curl 127.0.0.1:49559/stats

Graph：
curl 127.0.0.1:29669/stats
curl 127.0.0.1:39669/stats
curl 127.0.0.1:49669/stats

Storage
curl 127.0.0.1:29779/stats
curl 127.0.0.1:39779/stats
curl 127.0.0.1:49779/stats`
```
## 03nebula-stats-exporter 安装配置

### RPM/DEB 方式部署的 nebula，对应使用二进制方式部署 nebula-stats-exporte
```
# 下载
git clone https://github.com/vesoft-inc/nebula-stats-exporter.git

# 编译
cd nebula-stats-exporter
make build

# 创建config.yaml
vim config.yaml

# 内容
clusters:
  - name: nebula
    instances:
      - name: metad
        endpointIP: 127.0.0.1
        endpointPort: 19559
        componentType: metad
      - name: graphd
        endpointIP: 127.0.0.1
        endpointPort: 19669
        componentType: graphd
      - name: storaged0
        endpointIP: 127.0.0.1
        endpointPort: 19779
        componentType: storaged

# 启动服务
./nebula-stats-exporter --bare-metal --bare-metal-config=./config.yaml

# 服务正常启动，改为后台运行模式，截图留念
nohup ./nebula-stats-exporter --bare-metal --bare-metal-config=./config.yaml > nebula-stats-exporter.log  2>&1 &
```
![ 测试接口](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-4.png)

```
# 测试接口
curl 127.0.0.1:9100/metrics
```
### docker-compose部署nebula，对应使用docker方式nebula-stats-exporte

```
# # 创建config.yaml
vim config.yaml

# 内容
clusters:
  - name: nebula
    instances:
      - name: metad0
        endpointIP: 127.0.0.1
        endpointPort: 29559
        componentType: metad
      - name: metad1
        endpointIP: 127.0.0.1
        endpointPort: 39559
        componentType: metad
      - name: metad2
        endpointIP: 127.0.0.1
        endpointPort: 49559
        componentType: metad
      - name: graphd0
        endpointIP: 127.0.0.1
        endpointPort: 29669
        componentType: graphd
      - name: graphd1
        endpointIP: 127.0.0.1
        endpointPort: 39669
        componentType: graphd
      - name: graphd2
        endpointIP: 127.0.0.1
        endpointPort: 49669
        componentType: graphd
      - name: storaged0
        endpointIP: 127.0.0.1
        endpointPort: 29779
        componentType: storaged
      - name: storaged1
        endpointIP: 127.0.0.1
        endpointPort: 39779
        componentType: storaged
      - name: storaged2
        endpointIP: 127.0.0.1
        endpointPort: 49779
        componentType: storaged
# 启动，需要注意config.yaml路径按实际修改，我为了方便使用127.0.0.1 将-p 9100:9100 换成了--network=host，直接使用主机网络（因为容器部署使用bridge网络，127.0.0.1只能连接容器内）
docker run -d --restart=always --name nebula-stats-exporter -p 9100:9100 \
    -v "$(pwd)/deploy/bare-metal/config.yaml:/config.yaml" \
    vesoft/nebula-stats-exporter:v3.3.0 --bare-metal --bare-metal-config=/config.yaml

# 查看日志
docker logs -f nebula-stats-exporter

# 截图留念
```
![Prometheus](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-5.png)

## 04 整合 Prometheus 和 Grafana

### Prometheus 配置文件

```
# 编辑prometheus.yml
vim prometheus.yml

# 内容，根据实际IP填写
scrape_configs:
  - job_name: 'nebula-stats-exporter'
    static_configs:
      - targets: ['127.0.0.1:9100']

# 访问9090端口，查看是否正常
# 截图留念
```

### Grafana 配置

- 添加 Prometheus 数据源
![Grafana](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-6.png)
![Prometheus 数据源](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-7.png)
![Prometheus](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-6-27-8.png)
![Prometheus 数据源](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-9.png)
- 导入 Dashboard 样式

```
# 下载地址
https://github.com/vesoft-inc/nebula-stats-exporter/blob/master/deploy/grafana/nebula-grafana.json
```
![Dashboard](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-10.png)
![nebula-stats-exporter](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-11.png)
![nebula](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-12.png)

## 05总结

本文阐述了使用 nebula-stats-exporter 对 nebula 各个服务进行监控的方式，希望能对大家有所帮助。

作者：玖叁叁
校对&审核：kristain

图数据库可以高效地表达、存储和分析复杂关系和网络，在特定场景下有着不错的性能。本篇文章将会对二进制部署以及 docker-compose 部署两种部署方式使用 nebula-stats-exporter 进行说明，均使用目前最新版本 v3.8.0。

实践分享｜关于 nebula-stats-exporter 的使用

![ngbatis系列](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-12-1.jpg)

各位朋友好久不见，这个系列自从上次的《ngbatis系列丨操纵字节码实现xml变代理类》，至今久未更新了。今天的话题是：日常开发中容易碰到的问题。

## 项目集成类

**Q1：与存在 MyBatis 的项目集成**

在与使用了 MyBatis 的项目集成时，最重要的是实现四部分代码的两两分离，例如以下配置方式：

| - | Java 接口 | xml |
| --- | --- | --- |
| MyBatis | MapperScan | mybatis.mapper-locations=classpath:mapper/*.xml |
| NgBatis | SpringBootApplication.scanBasePackages | cql.parser.mapper-locations=ng-mapper/**/*.xml

1.Java层面，MapperScan 与 SpringBootApplication 中的 ScanBasePackages 二者所指向的包不存在交叉，即：让 MyBatis 发现不了NgBatis 的 Java 接口，同理，让 NgBatis 发现不了 MyBatis 的 Java 接口，避免重复发生会导致异常的动态代理行为。导致异常的原因有：

 - 当 MyBatis 扫描到 NgBatis 的 Java 接口，会使用访问关系型数据库的逻辑来代理访问图数据库的接口，与期望相悖。
 - 另外 NgBatis 再代理一次，一个接口下产生两个 Bean，会导致通过接口的单例注入报错。
 - NgBatis 实现动态代理机制的入口是 xml 中的 namespace，如果添加了类似 @Component 或者 @Mapper 的注解，同样会导致报错。

2.xml 层面，同样需要使 mybatis.mapper-locations 与 cql.parser.mapper-location 所指向的路径不存在交叉。设计之初有不当之处，默认值状态下，二者路径重叠。两个框架的解析逻辑与约束不同，如果 NgBatis 通过 cql.parser.mapper-locations 指定的路径，扫描到 MyBatis的 xml，可能导致解析出错，反之亦然。另外，cql.parser.mapper-locations 所指向的路径至少需要包含一个 xml 文件，这一点会考虑在后续的版本优化。

**Q2：与 ```spring-boot```3.x 集成**

在主分支中，保持的版本是与 ```spring-boot``` 2.x 的集成，如果需要与 ```spring-boot``` 3.x 集成，可以使用带有 ```-jdk17```后缀的版本。

**Q3：与 SpringCloud 集成**

扫描接口所在包的注解可以使用 ```@ComponentScan(...)```，同样需要注意 Q1 中所提的包路径范围。

**Q4：与存在 org.apache.shardingsphere 的项目集成**

NgBatis 中所使用的 Beetl 模板引擎依赖了 antlr4，shardingsphere 同样依赖了 antlr4，这其中就有可能会产生 jar 包版本的冲突。以 shardingsphere 5.2.0 (antlr-4.9.2) 与 NgBatis 1.2.2 (antlr-4.11.1) 为例，两个版本冲突的解决方式如下：

```
<dependency>
       <groupId>org.nebula-contrib</groupId>
       <artifactId>ngbatis</artifactId>
       <version>1.2.2</version>
        <exclusions>
            <exclusion>
                <groupId>com.ibeetl</groupId>
                <artifactId>beetl-antlr4.11-support</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>com.ibeetl</groupId>
        <artifactId>beetl-default-antlr4.9-support</artifactId>
        <version>3.15.10.RELEASE</version>
    </dependency>

```

在项目中引入 NgBatis 的同时，排除掉高版本的 antlr，然后尝试引用相对低版本的 antlr，如不是例子中所提的版本，可以在 maven 中查找 beetl antlr support 这个系列的包，并引入相近版本。

## 自定义 nGQL 用法问题

**Q1：参数占位符问题**

参数的使用有两个时机可以选择，假如现在有一个参数 param：

- 执行到数据库时，由数据库读取参数，参数格式为：```$param```，前提是数据库支持该参数位置的参数化，正常用在查询子句的 == 后；

- 执行到数据库前，由 NgBatis 组装到 xml 的 nGQL 模板中，参数格式为：```$param```；

- 如果参数位置是 Schema，可以使用```${ng.valueFmt(param)} ```，等价于 `${param}`；

- 当参数不能确定具体类型时，可以使用 ```${ng.valueFmt(param)} ```进行占位，NgBatis 会根据类型处理成符合语法结构的形式，如 String 类型会在前后追加引号，时间类型会转换成调用 date、datetime 等时间函数的字符串形式，进而完成 nGQL 组装。

- 在模板中，参数还存在两种类型，模板参数类型与 Java 对象类型。如果访问参数方法，可使用 ```@param.methodName```的方式，如 param 是一个 Map 类型，可以使用```@param.get('keyName')```。(1.18 调用 Java 方法与属性 · Beetl3 官方文档 · 看云：https://www.kancloud.cn/xiandafu/beetl3_guide/2138960)

**Q2：参数名称问题**

- 当 Java 接口只有一个参数，且为 Map 或对象类型时，可以直接使用 key 或者对象的属性名。否则默认参数名按所处方法的参数位置，取 ```p0```、```p1```...

- 为了代码更具可读性，可在参数名中，对参数追加注解：```@Param("xxx")```，需要注意的是，该注解的包名为：org.springframework.data.repository.query，如误使用了包含 ibatis 的包名，并不会加以识别。

**Q3：如何在在多个集合元素使用“```,```”分隔**

可以使用 ```${ng.join(list)}```，List 为传入的变量名。更多 NgBatis 的模板函数用法详见：(https://graph-cn.github.io/ngbatis-docs/dev-example/built-in-function.html)

**Q4：如何判断参数是否为空**

可以使用 ```isEmpty(param) ```进行判断。更多模板函数详见：(https://www.kancloud.cn/xiandafu/beetl3_guide/2138956)

**小结**

在 xml 中自定义 nGQL 的用法中，基类 NebulaDaoBasic 实现的方式遵循着相同的模板方式，意味着源码中的 NebulaDaoBasic.xml 中有更多详尽的用例可以提供参考，当然基类为了满足更具通用性，整体用法会显得比常规模板写法要复杂一些。

##  NgBatis 结构下进行拓展

以下方式如果想对既有类型进行覆盖，需要建立在项目软件包在 org.nebula.contrib 包之后，如：


```
@SpringBootApplication(scanBasePackages={"org.nebula.contrib", "com.example.xxx"})
```

**Q1：复杂对象作为返回值，如何处理**

可以使用继承抽象类的方式对不兼容的类型进行处理，如：


```
@Component
public class MyTypeHandler extends AbstractResultHandler<MyType, MyType> {

  @Override
  public MyType handle(MyType newResult, ResultSet result, Class resultType) {
    // 在当前位置，从 result 读取数据，填入 newResult 中
    return null;
  }
}
```

如果复杂类型需要支持集合的方式，还需要拓展一个集合的接口：

```

@Component
public class CollectionMyTypeHandler extends AbstractResultHandler<Collection, MyType> {
  
  @Autowired private MyTypeHandler itemHandler;
  
  @Override
  public MyType handle(Collection newResult, ResultSet result, Class resultType) {
    // 在当前位置，从 result 读取数据，填入 newResult 中
    // 取对应元素值，调用 itemHandler 然后调用 newResult.add 完成添加
    return newResult;
  }
}
```
**Q2：还有哪些接口可以拓展：**

1.主键生成接口：PkGenerator，可根据入参获得 Vid 的类型，然后选择使用雪花算法或者 UUID 等方式，完成主键生成策略的指定；

2.模板引擎接口：TextResolver，当模板引擎的实现方式发生替换，需要将 NebulaDaoBasic.xml 迁移到项目的 resources 中，并用新模板引擎的方式进行重写；

3.传入参数的转换接口：ArgsResolver，如现有传入模板参数的转换方案不能满足需求，可对其进行替换，自定义实现类，对 ArgsResolver 进行实现，并注册成组件；

4....

##  配置相关问题

**Q1：如何在控制台中输出 nGQL**


```
logging:
  level:
    org.nebula.contrib: DEBUG
```

**Q2：如何指定 mapper xml 的放置路径：**


```
cql:
  parser:
    # 更换开发者自定义的 xml 所在位置
    mapper-locations: ng-mapper/**/*.xml # 默认为 mapper/**/*.xml
```

## 报错类问题

**StackOverflowError**

- 场景1

  - 报错时机：模板引擎生成语法树时产生报错
  - 解决方式：指定虚拟机启动参数 -Xss2m

- 场景2

  - 报错时机：参数传入数据库时，会经历一个类型转换的过程，将 Java 对象转换成 Nebula-Java 的可接受的 Value 类型，当 Java 对象的值存在循环依赖时，即 a 对象是 b 对象的属性值之一，同时 b 对象也是 a 对象的属性值之一，会导致递归过深问题。当前最新版本 v1.2.2 还未在类型转换时，做空对象缓存来规避循环问题。

  - 解决方式 1：改变参数类的结构；

  - 解决方式 2：对不需要写入数据库的属性添加 @Transient 注解。

## 优化类问题

**第一种情况，查询语句组装耗时**

在 NgBatis 对模板引擎的使用中，有一个比较重的资源使用了懒加载的方式。日志输出对应的是：nGQL make up costs 370ms，如果想把这部分时间挪到服务启动时， 可以在项目中使用以下方式，提前完成资源加载：

```
@Bean
public TextResolver textResolver(TextResolver resolver) {
  resolver.resolve("", Collections.emptyMap());
  return resolver;
}
```

**第二种情况，执行查询的耗时**

另外还有可能耗时的环节发生在数据库的查询上，日志输出对应的是：query costs 1091ms 如果最小连接数为 0，那么也会在第一次查询时创建连接，也会比单纯的查询本身额外消耗一些时间：可以让最小连接数大于 0，从而在服务启动时，完成连接创建，减少初次查询耗时。


```
nebula:
  pool-config:
    min-conns-size: 1
```

## 关于多个图空间的使用问题

当项目需要跨越多个图空间进行数据读写时，有以下几种方式可以实现跨空间：
1.在实体类中追加 @Space("myspace") 指定 tag 所属空间

2.在 xml 中的 <mapper space="myspace" namespace="...xxxMapper">

3.在接口方法的标签中指定 space，如：
<select id="..." space="myspace">

以上三种方式可以按需选择。其中第三种方式还支持使用参数的方式，如：

```
<select id="spaceFromParam" space="${paramMySpace}" spaceFromParam="true">
        RETURN true;
    </select>

```

```paramMySpace```通过接口的参数传入。据我所知，有开发者在此用法的基础上实现了多租户场景的适配。

## 总结

目前将 NgBatis 集成到项目中出现得比较多的问题大体上都列在上面了，可能有一些问题的表象会跟列举的内容不太相同，但可以通过类比跟对应问题点附带的参考文档来完成。如果你在开发中碰到一些比较典型或者比较反直觉的问题，也可以留言讨论。

原文作者：大叶
作者公众号：大叶的技术栈
校对&审核：kristain



在项目中引入 NgBatis 的同时，排除掉高版本的 antlr，然后尝试引用相对低版本的 antlr，如不是例子中所提的版本，可以在 maven 中查找 beetl antlr support 这个系列的包，并引入相近版本。

NgBatis丨开发常见问题

![NebulaGraph 安装](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-1.jpg)

## NebulaGraph 安装

本次安装选择 NebulaGraph 最新版本 v3.8.0，采用 docker-compose 的方式部署，新版本的安装要比之前顺滑很多，赞~ 

1. 找一台服务器，安装好 docker 和 docker-compose

2.  下载项目

```
`$ git clone -b release-3.8 https://github.com/vesoft-inc/nebula-docker-compose.git` 
```

3.  安装

```
`mkdir -p /work/nebula

#复制docker-compose.yaml
cp ../nebula-docker-compose-3.8.0/docker-compose.yaml /work/nebula/

# 复制环境变量文件
cp ../nebula-docker-compose-3.8.0/.env /work/nebula/

# 修改.env，时区使用Asia/Shanghai
vim .env

TZ=Asia/Shanghai

# 启动
docker-compose up -d

# 查看启动结果
docker-compose ps是 git clone -b release-3.8 https://github.com/vesoft-inc/nebula-docker-compose.git

![git clone -b release-3.8](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-2.png)

Prometheus 安装

安装过程如下:
# 创建目录
mkdir -p /work/prometheus

# 创建应用子目录
# 启动脚本路径
mkdir -p /work/prometheus/bin
# 数据文件路径
mkdir -p /work/prometheus/data/prometheus
# 配置文件路径
mkdir -p /work/prometheus/conf
# 日志文件路径
mkdir -p /work/prometheus/logs

# 创建启动脚本
cd /work/prometheus/bin
vim start.sh

#内容
docker run -d --restart=always --name=prometheus \
        -p 9090:9090 \
        --log-opt max-size=10m \
        -v /etc/localtime:/etc/localtime:ro \
        -v /etc/timezone:/etc/timezone \
        -v /work/prometheus/conf/prometheus.yml:/etc/prometheus/prometheus.yml \
        -v /work/prometheus/data/prometheus:/prometheus \
        prom/prometheus --config.file=/etc/prometheus/prometheus.yml --web.enable-lifecycle --storage.tsdb.retention.time=7d
        
# 创建一个空的prometheus.yml
touch prometheus.yml

# 修改/work/prometheus/data/prometheus，目录权限
chown 65534:65534 prometheus/

# 启动
chmod 755 start.sh
./start.sh

# 查看启动日志，确认正常启动
docker logs -f prometheus`
```
![docker logs -f prometheus](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-3.png)


## Grafana 安装

安装过程如下：
```
`#创建目录
mkdir -p /work/grafana

#创建应用子目录

#启动脚本路径
mkdir -p /work/grafana/bin

#数据文件路径
mkdir -p /work/grafana/data/grafana

#日志文件路径
mkdir -p /work/grafana/logs

#创建启动脚本
cd /work/grafana/bin
vim start.sh

#内容
docker run -d --restart=always --name grafana \
        -p 3000:3000 \
        --log-opt max-size=10m \
        -e GF_AUTH_PROXY_ENABLED=true \
        -e GF_AUTH_ANONYMOUS_ENABLED=true \
        -e GF_SERVER_ENABLE_LOCAL_HEALTH_CHECK=false \
        -v /etc/localtime:/etc/localtime:ro \
        -v /etc/timezone:/etc/timezone \
        -v /work//grafana/data/grafana:/var/lib/grafana \
        prom/prometheus --config.file=/etc/prometheus/prometheus.yml --web.enable-lifecycle --storage.tsdb.retention.time=7d

# 创建一个空的prometheus.yml
touch prometheus.yml

# 修改/work/prometheus/data/prometheus，目录权限
chown 65534:65534 prometheus/

# 启动
chmod 755 start.sh
./start.sh

# 查看启动日志，确认正常启动
docker logs -f prometheus
`
```

## Grafana 安装

安装过程如下：

```
# 创建目录
mkdir -p /work/grafana
# 创建应用子目录
# 启动脚本路径
mkdir -p /work/grafana/bin
# 数据文件路径
mkdir -p /work/grafana/data/grafana
# 日志文件路径
mkdir -p /work/grafana/logs

# 创建启动脚本
cd /work/grafana/bin
vim start.sh

#内容
docker run -d --restart=always --name grafana \
        -p 3000:3000 \
        --log-opt max-size=10m \
        -e GF_AUTH_PROXY_ENABLED=true \
        -e GF_AUTH_ANONYMOUS_ENABLED=true \
        -e GF_SERVER_ENABLE_LOCAL_HEALTH_CHECK=false \
      -v /etc/localtime:/etc/localtime:ro \
        -v /etc/timezone:/etc/timezone \
        -v /work//grafana/data/grafana:/var/lib/grafana \
        harbor.neuqsoft.com/dockerhub/grafana/grafana

# 修改/work//grafana/data/grafana，目录权限
chown 472:472 grafana/

# 启动
chmod 755 start.sh
./start.sh

# 查看启动日志,确认正常启动
docker logs -f grafana

```

![docker logs -f grafana](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-4.png)

整合阶段

1. 调整 NebulaGraph，打开监控

```
`docker-compose down
# 编辑docker-compose.yaml文件
vim docker-compose.yaml

# 在graphd服务后边增加 - --enable_space_level_metrics,注意我有三个节点，都需要修改
 - --enable_space_level_metrics`
```

![enable_space_level_metrics](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-5.png)

```
 # 调整端口，将ws_http_port对应的端口映射出来
 # 使用29669，39669，49669对应graphd服务的三个节点19669
 # 以下为部分内容，注意我有三个节点，都需要修改
 - 29669:19669
 - 29669:19669
 - 29669:19669`

```
![启动 NebulaGraph](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-6.png)

```

# 启动 NebulaGraph
docker-compose up -d

# 检查启动状态
docker-compose ps

```
2. 配置 Prometheus


```

# 编辑配置文件
vim prometheus.yml

scrape_configs:
  - job_name: nebula-graph
    metrics_path: /stats
    static_configs:
     - targets:
       - 127.0.0.1:29669
       - 127.0.0.1:39669
       - 127.0.0.1:49669

# 重启服务
docker restart prometheus

```
3. Grafana 配置数源

![docker restart prometheus](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-7.png)

![Grafana 配置数源](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-8.png)

4. 官方自带的 metrics 接口请求地址和 Prometheus 要求的不一样，通过修改 metrics_path 配置，指定到了 /stats 访问地址。

其次，返回数据格式也和 Prometheus 要求的不一样，导致 Prometheus 识别节点全部都是 down

![Prometheus](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-9.png)

5.最后，采集到的数据，也没有被 Prometheus 存储，Grafana 也没办法读取到。

![ Prometheus](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-10.png)


## 填坑环节

1. 期间试过很多种方法，失败的就不说了，就说最后成功的
自己实现一个数据转换服务，将官方的 metrics 返回数据转换为Prometheus 要求的格式。

用 GO 实现了一个转换的工具，上代码：

```

package main

import (
    "flag"
    "fmt"
    "io/ioutil"
    "net/http"
    "os"
    "strings"
)

// 端点和端口进行变量声明
var (
    targetEndpoint string
    port           string
)

func main() {
    // 使用 flag 包解析命令行参数
    flag.StringVar(&port, "port", "8000", "HTTP server 监听端口")
    flag.StringVar(&targetEndpoint, "target", "http://nebula-graph.local:19669/metrics", "目标 metrics 端点地址")
    flag.Parse()

    // 注册 /metrics 路由
    http.HandleFunc("/metrics", handleMetrics)

    // 启动 HTTP 服务器
    fmt.Printf("服务器启动在端口 %s，抓取指标来自 %s\n", port, targetEndpoint)
    if err := http.ListenAndServe(":"+port, nil); err != nil {
        fmt.Printf("启动服务器时遇到错误: %s\n", err)
        os.Exit(1)
    }
}

// handleMetrics 是处理指标抓取的主函数
func handleMetrics(w http.ResponseWriter, r *http.Request) {
    // 从目标端点抓取原始指标数据
    resp, err := http.Get(targetEndpoint)
    if err != nil {
        http.Error(w, "抓取指标失败", http.StatusInternalServerError)
        return
    }
    defer resp.Body.Close()

    // 读取响应体内容
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        http.Error(w, "读取指标失败", http.StatusInternalServerError)
        return
    }

    // 重格式化指标
    metrics := reformatMetrics(string(body))
    fmt.Fprint(w, metrics) // 返回格式化后的指标
}

// reformatMetrics 将原始指标重格式化为 Prometheus 兼容的格式
func reformatMetrics(rawMetrics string) string {
    var formattedLines []string
    lines := strings.Split(rawMetrics, "\n") // 按行拆分

    for _, line := range lines {
        // 跳过注释行和空行
        if strings.HasPrefix(line, "#") || line == "" {
            formattedLines = append(formattedLines, line)
            continue
        }

        // 自定义重格式化逻辑
        // 比如：num_queries_hit_memory_watermark.rate.5=0 -> num_queries_hit_memory_watermark_rate_5{interval="5"} 0
        parts := strings.Split(line, "=")
        if len(parts) != 2 {
            // 跳过无效行
            continue
        }
        metric, value := parts[0], parts[1]

        // 处理 metric 部分，将其拆分为名称和区间
        metricParts := strings.Split(metric, ".")
        if len(metricParts) < 3 {
            continue  // 不符合预期格式则跳过
        }

        // 将名称和区间拼接成 Prometheus 格式
        baseName := strings.Join(metricParts[:len(metricParts)-2], "_") // 将名称部分合并
        interval := metricParts[len(metricParts)-1]
        metricType := metricParts[len(metricParts)-2]

        // 拼接成 Prometheus 格式的字符串
        formattedMetric := fmt.Sprintf("%s_%s{interval=\"%s\"} %s", baseName, metricType, interval, value)
        formattedLines = append(formattedLines, formattedMetric)
    }

    return strings.Join(formattedLines, "\n") // 将所有行合并为一个字符串
}# 编译后得到linux服务器可执行文件metrics_converter
# 启动服务
./metrics_converter -port=8081 -target=http://127.0.0.1:29669/stats

# 测试
curl http://127.0.0.1:8081/metrics

# ok数据格式对了，不要纠结为啥全是0，刚装的啥也没有..

```
![调整 Prometheus 配置文件](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-11.png)

2. 调整 Prometheus 配置文件，调整了一个演示如下


```

# # 编辑配置文件
vim prometheus.yml

scrape_configs:
  - job_name'nebula-graph'
    static_configs:
     - targets:
       - 127.0.0.1:

# 重启服务
docker restart prometheus

```
![docker restart prometheus](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-12.png)

3. 查看 Grafana 数据指标，已经可以正常制作图表了

![Grafana 数据指标](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-13.png)

4.由于原来不支持 Prometheus + Grafana，所以官方图表库没有能直接用的

## 总结

通过不断的尝试，终于实现了目标，现在看来运维工作确实需要一些开发的基础，希望这篇文章能给需要的人带来一丝丝帮助吧。

注意：全篇文章使用 127.0.0.1 是为了隐藏 IP，各位测试的时候请使用真实IP！！

作者：堕落飞鸟

校对 & 编辑：Kristain# 

通过不断的尝试，终于实现了目标，现在看来运维工作确实需要一些开发的基础，希望这篇文章能给需要的人带来一丝丝帮助吧。

实践分享｜使用 Prometheus 监控 NebulaGraph

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-01.jpg)

### 环境描述

首先来说下本文的背景信息，主要是从原先用了多年的 v1.0.0 版本升级到 NebulaGraph 最新的 v3.6.0 版本。下面是本文可能会用到的前提信息：

- 当前 NebulaGraph 版本：v1.0.0
- 目标 NebulaGraph 版本：v3.6.0
- nebula-client版本：com.vesoft:client:1.0.0-rc4.20200323

相信 NebulaGraph 社区有很多和我类似用着非最新发行版的企业用户，因为为了保障业务的稳定运行，依旧用着 v2.x.0 版本，或者是和我们一样用着 v1.0.0 版本。所以，很多人会问：升级？为什么要升级呢？

这是我的答案：v3.6.0 版本，或者说最新发行版，会比 v1.0.0 版本具有**更高的可维护性和稳定性、更完善的周边生态**。此外 NebulaGraph v1.0.0 版本**出问题基本上很难得到解决，另外扩缩容比较麻烦。**

### 升级需要考虑的点

和许多依旧用着老版本的用户一样，我们其实也是做了一段时间的挣扎选择了升级。下面是我们想到的升级需要考虑到的点：

1.nGQL 的兼容性；

2.原地升级 or 导出导入的方式？这里我们测试过，原地升级经测试不可用，而且还会影响在线业务，风险大；

3.如何保证升级不影响线上的业务；

4.如何处理升级时产生的增量数据；

5.升级后如何数据一致性比对；

6.如何进行新老 nebula 替换；

如果要排个优先级的话，第 3，5，6 相比其他几点会更重要。

### 升级方案

![升级方案](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-1.png)

这是大致的升级方案，大体分为三个部分：

**升级前准备**

有些准备工作需要完成：

1.收集、整合业务线相关的所有 nGQL 并进行 v3.6.0 版本测试，修改 nGQL 以兼容 v3.6.0 版本 nebula。

2.编写 nebula 同步服务，这里无法使用 nebula-spark-connector 进行同步，因为 nebula 版本跨的太大了。

3.编写数据流量比对逻辑。

4.搭建 NebulaGraph v3.6.0 版本新集群环境，这里可以临时关闭自动 Compaction 功能，来加快写入速度。

**注意：这里并非在原来的业务应用上进行更新，而是复制一个新的出来，因为同一个应用无法兼容两套不同版本的 nebula**。

### 执行升级

我们这里是借助了 MQ（消息队列，Message Queue）来中间处理了下数据。涉及到 MQ 的步骤有：

1.开启同步过程增量数据写入 MQ 进行积压；

2.开启 nebula 数据同步，应用 A 从 nebula v1.0.0 中读取出来发送到 MQ，然后应用 B 消费 MQ 消息写入到 nebula v3.6.0；

3.同步完毕后将 MQ 中积压的增量数据写入 nebula v3.6.0；

### 升级后处理

这里再简述下升级之后需要做的操作：

1.数据一致性比对，通过流量复制的方式发送到新的应用上进行重放结果比对；

2.逐步切流量到新 nebula v3.6.0 集群；

### 内核升级的详细设计

名词说明：

- biz-app：业务应用 App，作用连接 nebula v1.0.0 进行图数据操作；

- biz-app-new：biz-app 的复制版本，只不过改成了连接 v3.6.0 版本 nebula，并更新 nGQL 以兼容 nebula v3.6.0；

- nebula-sink-app：用于接收 nebula v3.6.0 版本的更新语句消息，并写入到 nebula v3.6.0 集群；

**第一步：开启增量数据写入 MQ 积压**

![MQ 积压](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-2.png)

第二步：同步 nebula v1.0.0 数据到 v3.6.0 集群

![nebula v1.0.0](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-3.png)

第三步：同步完毕后消费增量数据

![消费增量数据](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-4.png)

第四步：数据一致性比对

![数据一致性比对](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-5.png)

第五步：nebula v3.6.0 集群切流

![nebula v3.6.0 集群切流](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-6.png)

### nebula-client v3.6.0 版本 SDK 改造

本次客户端的改造，主要是支持下面功能：主备写入同步、主备读取分流、读写 SessionPool 隔离、连接池监控、nGQL 执行监控。

![SDK 改造](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-7.png)

### 遇到的问题以及解决方案

当然升级不是一步到位，我们也遇到了不少的问题。这里罗列了几个印象深刻的错误：

- 导出 Timestamp 属性字段报错

- 无法导出多版本数据（Schema 发生更改）

- 每次 Scan 中断只能从头开始，无法接着上次的 cursor 继续导出

- 指定扫描单个 Edge 或者 Tag 出现磁盘 IO 使用率100%（见：nebula v1.0.0 版本导出部分边或者点出现磁盘 IO 负载过高）

好在的是，这些问题我们都顺利解决了。下面来讲讲我们的解决方案：

### 导出 Timestamp 属性字段报错

这个问题产生的原因是因为 RowReader.java 中不支持 TIMESPTMP 字段。

![Timestamp](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-8.png)

**解决方案：**

**重写 RowReader 代码支持 Timestamp 字段：**


```
`public RowReader(Schema schema, long schemaVersion) {
        this.schemaVersion = schemaVersion;
        int idx = 0;
        for (ColumnDef columnDef : schema.columns) {
            PropertyDef.PropertyType type = PropertyDef.PropertyType.getEnum(columnDef.getType().getType());
            String name = columnDef.getName();
            switch (type) {
                case BOOL:
                    defs.add(new Pair(name, Boolean.class.getName()));
                    break;
                case INT:
                // 这里加入TIMESPTMAP属性识别
                case TIMESTAMP:
                case VID:
                    defs.add(new Pair(name, Long.class.getName()));
                    break;
                case FLOAT:
                    defs.add(new Pair(name, Float.class.getName()));
                    break;
                case DOUBLE:
                    defs.add(new Pair(name, Double.class.getName()));
                    break;
                case STRING:
                    defs.add(new Pair(name, byte[].class.getName()));
                    break;
                default:
                    throw new IllegalArgumentException("Invalid type in schema: " + type);
            }
            types.add(type);
            propertyNameIndex.put(name, idx);
            idx++;
        }
    }

public Property[] decodeValue(byte[] value, long schemaVersion) {
        List<byte[]> decodedResult = NebulaCodec.decode(value, defs.toArray(new Pair[defs.size()]),
                schemaVersion);
        Property[] properties = new Property[defs.size()];
        try {
            for (int i = 0; i < defs.size(); i++) {
                String field = defs.get(i).getField();
                PropertyType type = types.get(i);
                byte[] data = decodedResult.get(i);
                switch (types.get(i)) {
                    case BOOL:
                        properties[i] = getBoolProperty(field, data);
                        break;
                    case INT:
                   // 加入TIMESTAMP识别
                    case TIMESTAMP:
                    case VID:
                        properties[i] = getIntProperty(field, data);
                        break;
                    case FLOAT:
                        properties[i] = getFloatProperty(field, data);
                        break;
                    case DOUBLE:
                        properties[i] = getDoubleProperty(field, data);
                        break;
                    case STRING:
                        properties[i] = getStringProperty(field, data);
                        break;
                    default:
                        throw new IllegalArgumentException("Invalid type in schema: " + type);
                }
            }
        } catch (BufferUnderflowException e) {
            LOGGER.error("Decode value failed: " + e.getMessage());
        }
        return properties;
    }
`

```

**无法导出多版本数据（Schema 发生更改）**

这个原因是 ScanVertexProcessor 和 ScanEdgeProcessor 仅支持一个版本的数据解析：

![Schema 发生更改](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-9.png)

**解决方案：重写 ScanVertexProcessor 和 ScanEdgeProcessor 自动识别多版本数据：**


```
`public TagItem getSpecialVersionTagItem(String spaceName, int tagId, long version) {
        if (!spaceTagItemVersions.containsKey(spaceName)) {
            Map<Integer, Map<Long, TagItem>> tagVersionMap = Maps.newHashMap();
            List<TagItem> allTagItemList = getTags(spaceName);
            if (!allTagItemList.isEmpty()) {
                allTagItemList.forEach(tagItem -> tagVersionMap.computeIfAbsent(tagItem.getTag_id(), k -> Maps.newHashMap()).put(tagItem.getVersion(), tagItem));
                spaceTagItemVersions.put(spaceName, tagVersionMap);
            }
        }
        Map<Integer, Map<Long, TagItem>> tagVersionMap = spaceTagItemVersions.get(spaceName);
        if (Objects.isNull(tagVersionMap)) {
            return null;
        }
        return tagVersionMap.getOrDefault(tagId, Collections.emptyMap()).get(version);
    }

private RowReader getRowReader(String spaceName, ScanVertex scanTag, Map<Integer, RowReader> readers) {
        int tagId = scanTag.getTagId();
        // 解析当前tag数据的schema版本
        long schemaVersion = NebulaUtils.parseSchemaVersion(scanTag.getValue());
        Map<Integer, Map<Long, RowReader>> tagVersionReaderMap = spaceTagVersionReaders.computeIfAbsent(spaceName, k -> new ConcurrentHashMap<>());
        Map<Long, RowReader> versionReaderMap = tagVersionReaderMap.computeIfAbsent(tagId, k -> new ConcurrentHashMap<>());
        RowReader reader = versionReaderMap.get(schemaVersion);
        if (reader != null) {
            return reader;
        }
        //构建对应schema版本的RowReader
        TagItem tagItem = metaClient.getSpecialVersionTagItem(spaceName, tagId, schemaVersion);
        if (tagItem != null) {
            log.debug("Add special version tagItem | spaceName:{} | tagId:{} | schemaVersion:{}", spaceName, tagId, schemaVersion);
            versionReaderMap.computeIfAbsent(schemaVersion, k -> new RowReader(tagItem.schema, tagItem.version));
            return versionReaderMap.get(schemaVersion);
        }
        RowReader rowReader = readers.get(tagId);
        if (rowReader == null) {
            log.error("Not match vertex reader | spaceName:{} | tagId:{} | schemaVersion:{} | data={}", spaceName, tagId, schemaVersion, Hex.encodeHexString(scanTag.value));
        }
        return rowReader;
    }
//解析数据的schema版本，根据nebula源码翻译成的java代码
public static long parseSchemaVersion(byte[] row) {
        if (row == null || row.length == 0) {
            System.err.println("Row data is empty, so there is no schema version");
            return 0;
        }
        // The first three bits indicate the number of bytes for the
        // schema version. If the number is zero, no schema version
        // presents
        int verBytes = row[0] >> 5;
        int ver = 0;
        if (verBytes > 0) {
            if (verBytes + 1 > row.length) {
                // Data is too short
                // System.err.println("Row data is too short");
                return 0;
            }
            // Schema Version is stored in Little Endian
            for (int i = 0; i < verBytes; i++) {
                ver |= ((int) row[i + 1] << (8 * i));
            }
        }
        return ver;
    }
`

```

**每次 Scan 中断只能从头开始，无法接着上次的 cursor 继续导出**

这个问题发生的原因是因为 StorageClient 中的 scan 方法并未支持 cursor 参数传入：

![StorageClient](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-10.png)

**解决方案：重写 StorageClient 提供可传入 cursor 参数，每次 next 之后将 cursor 保存到数据库中，中断重新跑的时候使用之前的 cursor：**


```
`//增加cursor参数
public Iterator<ScanVertexResponse> scanVertex(
            String space, int part, Map<String, List<String>> returnCols, boolean allCols,
            int limit, long startTime, long endTime, byte[] cursor) throws IOException {
        HostAndPort leader = getLeader(space, part);
        if (Objects.isNull(leader)) {
            throw new IllegalArgumentException("Part " + part + " not found in space " + space);
        }

        int spaceId = metaClient.getSpaceIdFromCache(space);
        ScanVertexRequest request = new ScanVertexRequest();
        Map<Integer, List<PropDef>> columns = getVertexReturnCols(space, returnCols);
        request.setSpace_id(spaceId)
                .setPart_id(part)
                .setReturn_columns(columns)
                .setAll_columns(allCols)
                .setLimit(limit)
                .setStart_time(startTime)
                .setEnd_time(endTime)
               //设置cursor参数到request中
                .setCursor(cursor);

        return doScanVertex(space, leader, request);
    }
`


```

**指定扫描单个 Edge 或者 Tag 出现磁盘 IO 使用率 100%**

问题的原因：当 Space 中部分点或者边数量极大（比如几百亿），部分点或者边数据极小（比如几百万），当扫描极小的点或者边的时候就会出现磁盘 IO 使用率 100%；

**解决方案：以扫描所有的点或者边，不指定单个 Edge 或者 Tag。**


### nebula 同步服务设计

设计原则：

- 导出时不能影响线上 nebula 服务

- 尽量充分使用 nebula 服务资源进行同步

- 能够实时监控同步进度

- 可以随时停止/启动同步任务

设计要点：

- 自动适配不同时间段，不同导出频率和单次扫描数据量

- 根据 nebula 服务器的压力自动调整扫描任务数和频率

- 自动将扫描任务均衡到每台 nebula 服务器，避免出现 nebula 集群服务器负载不一致的情况

**重点问题解决**

这里着重讲讲如何解决一些具体的问题：

问题：每台 nebula-storaged 节点有着不同的 partition 分布，处理扫描任务越多 nebula-storaged 服务器负载就越高，如何实现每台 nebula-storaged 处理 Scan 扫描任务的数量一样？

**解决方案：**

1.改造 StorageClient 支持指定 storage address 进行 scan 操作；

2.通过 nebula-client 执行 show parts 拿到每个 part 对应的 leader 分布；

3.根据 part 对应 leader 分布，即可进行指定 part 同步均衡到每台 nebula-storaged 服务器上。

问题：如何做自动同步流控，主要针对源头 nebula，也就是从哪里导出。

主要从 3 个方面解决问题：

1.扫描频率

2.扫描行数

3.scan 任务数

扫描流控：


```
`//开启SCAN操作并指定游标，此游标是上次scan保存下来的
                Iterator<RESP> iterator = scan(client, space, tagOrEdgeNameList, part, statusDomain.getNextCursor());
                boolean isScanLimitConfigIterator = (iterator instanceof ScanLimitConfigIterator);
                while (iterator.hasNext()) {
                    if (isScanLimitConfigIterator) {
                        //设置scan行数，这里根据不同的时间段、机器的负载返回不同的值
                        int scanLimit = nebulaScanLimitController != null ? nebulaScanLimitController.getLimit() : this.scanLimit;
                        ((ScanLimitConfigIterator<?>) iterator).setScanLimit(scanLimit);
                    }
                    Result<RESP> result = scanNext(dataProcessor, iterator);
                    //将查询结果组装成insert语句并发送到MQ
                    writeResult(result);
                    //保存游标到数据库中
                    saveNextCursor(result.getResp());
                    //控制扫描频率
                    Optional.ofNullable(nebulaScanFlowController).ifPresent(flowController -> flowController.controlConsumeFlow(storageIp));
                }
`


```

scan 任务自动缩减：


```
`private void autoReduceTask() {
        log.debug("Start autoReduceTask....");
        //从数据库中查询当前处理的任务列表
        List<NebulaDataScanTaskEntity> taskList = queryProcessingTaskList();
        //遍历处理中的任务列表，统计每台机器当前处理的任务数量，如果超过限制，则停止超出任务
        List<NebulaDataScanTaskEntity> needCancelTaskList = calCancelTaskList(taskList);
        if (needCancelTaskList.isEmpty()) {
            log.debug("AutoReduceTask is fail, needCancelTaskList is empty");
            return;
        }
        Set<Long> cancelTaskIdList = needCancelTaskList.stream().map(NebulaDataScanTaskEntity::getId).collect(Collectors.toSet());
        log.info("Need cancel task list: {}", cancelTaskIdList);
        //取消需要停止的任务
        cancelSpecialTask(cancelTaskIdList);
    }

//计算需要取消的任务列表
private List<NebulaDataScanTaskEntity> calCancelTaskList(List<NebulaDataScanTaskEntity> taskList) {
        Map<String, List<NebulaDataScanTaskEntity>> nodeProcessingTaskCountMap = taskList.stream().collect(Collectors.groupingBy(NebulaDataScanTaskEntity::getScanStorageHost));
        List<NebulaDataScanTaskEntity> needCancelTaskList = new ArrayList<>();
        for (Map.Entry<String, List<NebulaDataScanTaskEntity>> et : nodeProcessingTaskCountMap.entrySet()) {
            List<NebulaDataScanTaskEntity> nodeProcessingTaskList = et.getValue();
            //根据节点并发限制（也就是一个nebula-storaged节点能处理几个scan任务），计算需要停止的任务
            int nodeConcurrencyLimit = nebulaNodeConcurrencyLimitController.getNodeConcurrencyLimit(HostAndPort.fromString(et.getKey()).getHostText());
            if (nodeProcessingTaskList.size() > nodeConcurrencyLimit) {
                //这里根据id进行排序，为了解决多机器并发取消问题
                Collections.sort(nodeProcessingTaskList, Comparator.comparing(NebulaDataScanTaskEntity::getScanTotalRowCount));
                needCancelTaskList.addAll(nodeProcessingTaskList.subList(0, nodeProcessingTaskList.size() - nodeConcurrencyLimit));
            }
        }
        return needCancelTaskList;
    }
`


```


流控配置信息：

![流控配置信息](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-11.png)

以上，便是我完成的内核升级工作的分享。如果有你想了解更具体的细节，请留言评论。

作者：江一旺

校对 & 编辑：kristain

对图数据库 NebulaGraph 感兴趣？欢迎前往 GitHub ✨ 查看源码：[https://github.com/vesoft-inc/nebula；](https://github.com/vesoft-inc/nebula)

v3.6.0 版本，或者说最新发行版，会比 v1.0.0 版本具有更高的可维护性和稳定性、更完善的周边生态。此外 NebulaGraph v1.0.0 版本出问题基本上很难得到解决，另外扩缩容比较麻烦。

实践分享｜记录 NebulaGraph 从 v1.0.0 升级到 v3.6.0 版本的心路历程


![基于 raft-listener 实现的 nebula ](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-22.jpg)

### 背景以及需求

1.线上业务对数据库可用性可靠性要求较高，要求需要有双 AZ 的主备容灾机制。

2.主备集群要求数据和 schema 信息实时同步，数据同步平均时延要求在 1s 之内，p99 要求在 2s 之内。

3.主备集群数据要求一致

4.要求能够在主集群故障时高效自动主备倒换或者手动主备倒换，主备倒换期间丢失的数据可找回。


### 为什么使用 Listener

```
Listener：这是一种特殊的 Raft 角色，并不参与投票，也不能用于多副本的数据一致性。
```
![Listener](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-22-2.jpg)

原本的 NebulaGraph 中的 Listener 是一个 Raft 监听器，它的作用是将数据异步写入外部的 Elasticsearch 集群，并在查询时去查找 ES 以实现全文索引的功能。

这里我们需要的是 **Listener 的监听能力**，用于**快速同步数据到其他集群**，并且是异步的执行，不影响主集群的正常读写。

这里我们需要定义两个新的 Listener 类型：

1.Meta Listener：用于同步表结构以及其他元数据信息

2.Storage Listener：用于同步 storaged 服务的数据

![storaged 服务](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-22-3.jpg)

这样 storaged 服务和 metad 服务的 part leader 节点接受到写请求时，除了同步一份数据给 follower 节点，也会同步一份给各自的 listener 节点。

### 备集群如何接受数据？

现在我们面临几个问题：

1.两个新增 Listener 在接收到 leader 同步的日志后，应该如何再同步给备集群？

2.我们需要匹配和解析不同的数据操作，例如添加点、删除点、删除边、删除带索引的数据等等操作

3.我们需要将解析到的不同操作的数据重新组装成一个请求发送给备集群的 storaged 服务和 metad 服务

通过走读 nebula-storaged 的内核代码我们可以看到，无论是 metad 还是 storaged 的各种创建删除表结构以及各种类型数据的插入，最后都会序列化成一个 wal 的 log 发送给 follower 以及 listener 节点，最后存储在 RocksDB 中。

因此，我们的 listener 节点需要具备从 log 日志中解析并识别操作类型的能力，和封装成原请求的能力，因为我们需要将操作同步给备集群的 metad 以及 storaged 服务。

这里涉及到一个问题，主集群的 listener 需要如何感知备集群？备集群 metad 服务的信息以及 storaged 服务的信息？从架构设计上来看，两个集群之间应该有一个接口通道互相连接，但又不干涉，如果由 listener 节点直接发送请求给备集群的 nebula 进程，两个集群的边界就不是很明显了。所以这里我们再引入一个备集群的服务 listener 服务，它用于接收来自主集群的 listener 服务的请求，并将请求转发给自己集群的 metad 以及 storaged 服务。

这样做的好处。两边集群的服务模块是对称的，方便我们后面快速地做主备切换。

![Listener 节点](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-22-4.jpg)

### Listener 节点的管理和可靠性

为了保证双 AZ 环境的可靠性，很显然 Listener 节点也是需要多节点多活的，在 nebula 内核源码中是有对于 listener 的管理逻辑，但是比较简单，我们还需要设计一个 ListenerManager 实现以下几点能力：

1.listener 节点注册以及删除命令

2.listener 节点动态负载均衡（尽量每个 space 各个 part 分布的 listener 要均匀）

3.listener 故障切换

节点注册管理以及负载均衡都比较简单好设计，比较重要的一点是故障切换应该怎么做？


### listener 故障切换的设计

listener 节点故障切换的需求可以拆分为以下几个部分：

1.listener 同步 wal 日志数据时周期性记录同步的进度（commitId && appendLogId）

2.ListenerManager 感知到 listener 故障后，触发动态负载均衡机制，将故障 listener 的 part 分配给其他在运行的 listener

3.分配到新 part 的 listener 们获取原先故障 listener 记录的同步进度，并以该进度为起始开始同步数据


```

至于 listener 同步 wal 日志数据时周期性记录同步的进度应该记录到哪里？可以是存储到 metad 服务中，也可以存储到 storaged 服务对应的 part 中。

```
### nebula 主备切换设计

在聊主备切换之前，我们还需要考虑一件事，那就是双 AZ 环境中，应该只能有主集群是可读可写的，而其他备集群应该是只读不能写。这样是为了保证两边数据的最终一致性，备集群的写入只能是由主集群的 listener 请求来写入的，而不能被 graphd 服务的请求写入。

所以我们需要对集群状态增加一种“**只读模式**”，在这种只读模式下，表明当前集群状态是处于备集群的状态，拒绝来自 graphd 服务的写操作。同样的，备集群的 listener 节点处在只读状态时，也只能接收来自主集群的请求并转发给备集群的进程，拒绝来自备集群的 wal 日志同步。
![graphd](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-22-5.jpg)

主备倒换发生时，需要有以下几个动作：

1.主集群的每个 listener 记录自己所负责的 part 的同步进度（commitId && appendLogId）

2.备集群的 nebula 服务转换为可写

3.备集群的 listener 节点转换为可写，并且开始接收来自自己集群的 metad 和 storaged 进程的 wal 日志

4.主集群的 listener 以及各个服务转换为只读状态，开始接收来自新的主集群的数据同步请求

这几个动作细分下来，最主要的内容就是状态转换以及上下文信息保存和同步，原主集群需要保存自己主备切换前的上文信息（比如同步进度），新的主集群需要加载自己的数据同步起始进度（从当前最新的 commitLog 开始）

### 主备切换过程中的数据丢失问题

很明显，在上面的设计中，当主备切换发生时，会有一段时间的“双主”的阶段，在这个阶段内，原主集群的剩余日志已经不能再同步给备集群了，这就是会被丢失的数据。如何恢复这些被丢失的数据，可能的方案有很多，因为原主集群的同步进度是有记录的，有哪些数据还没同步完也是可以查询到的，所以可以手动或者自动去单独地同步那一段缺失数据。

当然这种方案也会引入新的问题，这段丢失地数据同步给主集群后，主集群会再次同步一遍回现在的备集群，一段 wal 数据的两次重复操作，不知道为引起什么其他的问题。

所以关于主备切换数据丢失的问题，我们还没有很好的处理方案，感兴趣的伙伴欢迎前往『原文』在评论区讨论。

对图数据库 NebulaGraph 感兴趣？欢迎前往 GitHub ✨ 查看源码：[https://github.com/vesoft-inc/nebula](https://github.com/vesoft-inc/nebula)；

通过走读 nebula-storaged 的内核代码我们可以看到，无论是 metad 还是 storaged 的各种创建删除表结构以及各种类型数据的插入，最后都会序列化成一个 wal 的 log 发送给 follower 以及 listener 节点，最后存储在 RocksDB 中。

架构设计——基于 raft-listener 实现的 nebula 实时同步的高效双集群主备环境

![基于内核 2.x 和 3.x 的可行 IP 替换方案](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-22-1.jpg)

在 NebulaGraph 的论坛上，有帖子教你如何《在 ip 变更之后保持原有的集群服务正常运行》。但这个帖子还是偏理论的，在本文一线工程师带来他的实操以及踩坑分享，带你进一步走进生产环境来实现 IP 的更换。

⚠️ 注意：虽然本文是实操经验分享，但是修改生产环境是个高危操作，如果你对相关服务不了解情况下不建议按照本文实践。此外，操作之前请再三备份数据。

### 背景信息

当你的集群节点的 IP 要更换时，可以通过以下步骤实现 IP 替换，并不需要重新导数据。

本文以三节点集群为例，将原先的机器 IP：192.168.16.1、192.168.16.2、192.168.16.3，更换为新的地址 IP：196.168.16.17、192.168.16.18、192.168.16.19。

此外，本文还提供将原先服务 IP:Port 地址变更为 Hostname:Port 的形式，在这里用域名 new-node1、new-node2、new-node3 来表示。

### 具体实践步骤

更换机器的 IP 需要经过下面的步骤：
- 变更 IP 信息：
  - 更新所有节点参数文件的老 IP 到新地址
  - 启动 meta 和 graph 服务
- 集群 meta 数据变更
  - 查看新集群 meta leader 节点
  - 修改 meta 中的 storage 信息
- 调整集群 storage 服务
  - 每台 storage 删除 cluster.id
  - 启动所有 storage 服务
  - 添加新 hosts 删除老 hosts
- 结果验证
  - 检查服务是否正常

### 变更 IP 信息

用 **sed** 命令修改安装目录下 **etc** 子目录下以 **conf **结尾的文件，下面的 220 表示老 IP，new-node 表示新的域名。
IP 换 IP 的，请在 **etc** 目录下分别执行以下 3 条命令：
```
$ sed -i  '/s/192\.168\.16\.1/192\.168\.16\.17/g' *.conf
$ sed -i  '/s/192\.168\.16\.2/192\.168\.16\.18/g' *.conf
$ sed -i  '/s/192\.168\.16\.3/192\.168\.16\.19/g' *.conf
```
IP 换域名的，请在**etc**目录下分别执行以下 3 条命令：
```
$ sed -i  '/s/192\.168\.16\.1/new-node1/g' *.conf
$ sed -i  '/s/192\.168\.16\.2/new-node2/g' *.conf
$ sed -i  '/s/192\.168\.16\.3/new-node3/g' *.conf
```

**这里说下采用域名形式的好处，如果你采用域名形式来访问服务，下次更换 IP 的时候只需要替换机器 hosts 文件就好，不需要做额外操作了！！！**

采用 IP 换域名形式的小伙伴记得修改下每台机器的 hosts 文件：

```
$ vi /etc/hosts
196.168.16.17   new-node1
196.168.16.18   new-node2
196.168.16.19   new-node3
```
一切稳妥之后，IP 换 IP 或者 IP 换域名的小伙伴来启动下 meta 和 graph 服务，以便进行后续的 meta 信息替换工作。
```
$ /usr/local/nebula/scripts/nebula.service start metad
$ /usr/local/nebula/scripts/nebula.service start graphd
```

### 集群 meta 信息变更

因为 meta 信息替换需要从 meta leader 开始，这里我们先查看下新集群 meta leader 节点：

如果你新的 IP 表达是 IP 则会看到下面的结果：

```
$ ./nebula-console3.0  -address 192.168.16.17 -port 9669 -u root -p nebula

Welcome to Nebula Graph!

(root@nebula) [(none)]> show meta leader
+--------------------------+---------------------------+
| Meta Leader              | secs from last heart beat |
+--------------------------+---------------------------+
| "192.168.16.18:9559"     | 4                         |
+--------------------------+---------------------------+
Got 1 rows (time spent 282/871 us)

```
如果你的新的 IP 表达是域名 hostsname 形式，则可以看到下面的结果：

```
$ ./nebula-console3.0  -address "new-node1" -port 9669 -u root -p nebula

Welcome to Nebula Graph!

(root@nebula) [(none)]> show meta leader
+--------------------------+---------------------------+
| Meta Leader              | secs from last heart beat |
+--------------------------+---------------------------+
| "new-node2:9559"         | 4                         |
+--------------------------+---------------------------+
Got 1 rows (time spent 282/871 us)
```

下面，最重要的一步：**修改 meta 中的 storage 信息**。

IP 换 IP 参考下面步骤：

这里的 192.168.16.18 为上一步查到的 meta leader 节点，**from** 和 **to** 参数分别对应老 IP 和新 IP。

如果返回“Replace Host in partition successfully”即为成功。

```

curl -G "http://192.168.16.18:19559/replace?from=192.168.16.1:9779&to=192.168.16.17:9779"
curl -G "http://192.168.16.18:19559/replace?from=192.168.16.2:9779&to=192.168.16.18:9779"
curl -G "http://192.168.16.18:19559/replace?from=192.168.16.3:9779&to=192.168.16.19:9779"
```

IP 换域名参考下面步骤：

这里的 new-node2 为上一步查到的 meta leader 节点，from 和 to 参数分别对应老 IP 和新地址。

如果返回“Replace Host in partition successfully”即为成功。

```
curl -G "http://new-node2:19559/replace?from=192.168.16.1:9779&to=new-node1:9779"
curl -G "http://new-node2:19559/replace?from=192.168.16.2:9779&to=new-node2:9779"
curl -G "http://new-node2:19559/replace?from=192.168.16.3:9779&to=new-node3:9779"
```

⚠️ 注意：如果你用的 Nebula 内核版本为 3.x 版本， **from&to** 地址后面要跟端口号 port；如果你用的内核版本是 2.x，则不需要跟端口号。

### 踩坑血泪史

这里说个之前实践时踩过的坑：在**内核 3.x 版本里，上面 from&to 的端口一定不能写错**。如果写错会导致 meta 里 partition 的信息中的主机 host replace 失败，storaged 判断老的 space 不存在，就会自动清除所有数据！！！

日志信息如下：

```
I20240402 19:15:08, 243983 98979 NebulaStore.cpp:96] Start the raft service. ..
120240202 19:15:08, 249043 98979 NebulaSnapshotManager.cpp:25] Send snapshot is rate limited to 10485760 for each part by default
I20240402 19:15:08, 252173 98979 RaftexService.cpp:47] Start raft service on 9780
I20240402 19:15:08, 252661 98979 NebulaStore.cpp:108] Register handler..
I20240402 19:15:08, 252676 98979 NebulaStore.cpp:136] Scan the local path, and init the spaces_
I20240402 19:15:08, 252732 98979 NebulaStore.cpp:144] Scan data path "/data1/nebula/nebula/0"
I20240402 19:15:08, 252741 98979 NebulaStore.cpp:144] Scan data path "/data1/nebula/nebula/1"
I20240402 19:15:08, 252750 98979 NebulaStore.cpp:163] Remove outdated space 1 in path /data1/nebula/nebula/1
I20240402 19:15:08, 252756 98979 NebulaStore.cpp:888] Try to remove directory: /data1/nebula/nebula/1
I20240402 19:15:51, 447275 98979 NebulaStore.cpp:890] Directory removed: /data1/nebula/nebula/1
I20240402 19:15:51, 447345 98979 NebulaStore.cpp:144] Scan data path "/data2/nebula/nebula/1"
I20240402 19:15:51, 447361 98979 NebulaStore.cpp:163] Remove outdated space 1 in path /data2/nebula/nebula/1
I20240402 19:15:51, 447367 98979 NebulaStore.cpp:888] Try to remove directory: /data2/nebula/nebula/1
I20240402 19:16:35, 420459 98979 NebulaStore.cpp:890] Directory removed: /data2/nebula/nebula/1
I20240402 19:16:35, 420529 98979 NebulaStore.cpp:144] Scan data path "/data3/nebula/nebula/1"
I20240402 19:16:35, 420545 98979 NebulaStore.cpp:163] Remove outdated space 1 in path /data3/nebula/nebula/1
I20240402 19:16:35, 420552 98979 NebulaStore.cpp:888] Try to remove directory: /data3/nebula/nebula/1
I20240402 19:17:21, 259413 98979 NebulaStore.cpp:890] Directory removed: /data3/nebula/nebula/1
I20240402 19:17:21, 259485 98979 NebulaStore.cpp:144] Scan data path "/data4/nebula/nebula/1"
I20240402 19:17:21, 259500 98979 NebulaStore.cpp:163] Remove outdated space 1 in path /data4/nebula/nebula/1
I20240402 19:17:21, 259506 98979 NebulaStore.cpp:888] Try to remove directory: /data4/nebula/nebula/1
I20240402 19:18:08, 185812 98979 NebulaStore.cpp:890] Directory removed: /data4/nebula/nebula/1
I20240402 19:18:08, 185892 98979 NebulaStore.cpp:144] Scan data path "/data5/nebula/nebula/1"
I20240402 19:18:08, 185909 98979 NebulaStore.cpp:163] Remove outdated space 1 in path /data5/nebula/nebula/1
126240402 19:18:08, 185015 98879 NebulaStore.cpp:888] Try to remove directory: /data5/nebula/nebula/1
I20240402 19:18:55, 286984 98979 NebulaStore.cpp:890] Directory removed: /data5/nebula/nebula/1
I20240402 19:18:55, 287062 98979 NebulaStore.cpp:144] Scan data path "/data6/nebula/nebula/1"
I20240402 19:18:55, 287079 98979 NebulaStore.cpp:163] Remove outdated space 1 in path /data6/nebula/nebula/1
I20240402 19:18:55, 287086 98979 NebulaStore.cpp:888] Try to remove directory: /datab/nebula/nebula/1
I20240402 19:19:49, 058575 98979 NebulaStore.cpp:890] Directory removed: /data6/nebula/nebula/1
I20240402 19:19:49, 058643 98979 NebulaStore.cpp:311] Init data from partManager for "new-node1":9779
I20240402 19:19:49, 058679 98979 StorageServer.cpp:278] Init LogMonitor
I20240402 19:19:49, 058822 98979 StorageServer.cpp:130] Starting Storage HTTP Service
I20240402 19:19:49, 059319 98979 StorageServer.cpp:134] Http Thread Pool started
I20240402 19:19:49, 062161 99318 WebService.cpp:130] Web service started on HTTP[19779]
I20240402 19:19:49, 082093 98979 RocksEngineConfig.cpp:386] Emplace rocksdb option max_background_jobs=64
120240402 19:19:49, 082144 98979 RocksEngineConfig.cpp:386] Emplace rocksdb option max_subcompactions=64
126240402 19:19:49, 082334 98979 RocksEngineConfig.cpp:286] Emplace rocksdb option max_bytes_for_level_base=268435456
120240402 19:19:49, 082346 98979 RocksEngineConfig.cpp:386] Emplace rocksdb option max_write_buffer_number=4
I20240402  19:19:49, 082352 98979 RocksEngineConfig.cpp:386] Emplace rocksdb option write_buffer_size=67108864
I20240402  19:19:49, 082358 98979 RocksEngineConfig.cpp:386] Emplace rocksdb option disable_auto_compaction=false
120240402 19:19:49, 082590 98979 RocksEngineConfig.cpp:386] Emplace rocksdb option block_size=8192
120240402 19:19:49, 120257 60324 EventListener.h:21] Rocksdb start compaction column family: default because of LevelL0FilesNum, status: Ok, compacted 4 files into 0.
I20240402  19:19:49, 120302 98979 RocksEngine.cpp:117] open rocksdb on /data1/nebula/nebula/0/0/data
120240402 19:19:49, 120452 96979 AdminTaskManager.cpp:22] max concurrent subtasks: 10

```

注意上面各种 remove 的操作，它是在删除数据啊！！！所以一定要确保端口正确。最后，操作前可以将 auto_remove_invalid_space 参数关闭，万一误操作也不会清数据！

### 调整集群 storage 服务

下面，我们来删除下 cluster.id 信息。前往每台 storage 机器，删除其 cluster.id 文件：

```
$ cd /usr/local/nebula
$ rm -rf cluster.id
```

全部删除完之后，启动所有 storage 服务：

```
$ /usr/local/nebula/scripts/nebula.service start storaged
```
这步操作如果你的内核是 2.x 版本，请跳过（2.x 不需要额外执行 **ADD HOSTS**）。

添加新的 storage hosts 删除老的 storage hosts。

IP 换 IP，参考：

```

#添加
$ ./nebula-console3.0  -address 196.168.16.17 -port 9669 -u root -p nebula

Welcome to Nebula Graph!

(root@nebula) [(none)]> add hosts 196.168.16.17:9779

Execution succeeded (time spent 13720/14409 us) 

(root@nebula) [(none)]> add hosts 196.168.16.18:9779

Execution succeeded (time spent 13720/14409 us)

(root@nebula) [(none)]> add hosts 196.168.16.19:9779

Execution succeeded (time spent 13720/14409 us)

#删除
(root@nebula) [(none)]> drop hosts 192.168.16.1:9779

Execution succeeded (time spent 13720/14409 us)

root@nebula) [(none)]> drop hosts 192.168.16.2:9779

Execution succeeded (time spent 13720/14409 us)

root@nebula) [(none)]> drop hosts 192.168.16.3:9779

Execution succeeded (time spent 13720/14409 us)

```
IP 换域名，请确保执行下面命令所在的机器的 hosts 文件配有域名和 IP 映射。参考：

```

#添加
$ ./nebula-console3.0  -address "new-node1" -port 9669 -u root -p nebula

Welcome to Nebula Graph!

(root@nebula) [(none)]> add hosts "new-node1":9779

Execution succeeded (time spent 13720/14409 us) 

(root@nebula) [(none)]> add hosts "new-node2":9779

Execution succeeded (time spent 13720/14409 us)

(root@nebula) [(none)]> add hosts "new-node3":9779

Execution succeeded (time spent 13720/14409 us)

#删除
(root@nebula) [(none)]> drop hosts 192.168.16.1:9779

Execution succeeded (time spent 13720/14409 us)

root@nebula) [(none)]> drop hosts 192.168.16.2:9779

Execution succeeded (time spent 13720/14409 us)

root@nebula) [(none)]> drop hosts 192.168.16.3:9779

Execution succeeded (time spent 13720/14409 us)

```
最后，检查服务是否正常：

```
(root@nebula) [(none)]> show hosts storage
+----------------+------+-----------+-----------+--------------+-------------+
| Host           | Port | Status    | Role      | Git Info Sha | Version     |
+----------------+------+-----------+-----------+--------------+-------------+
| "new-node1"    | 9779 | "ONLINE"  | "STORAGE" | "b062493"    | 3.6.0.      |
| "new-node2"    | 9779 | "ONLINE"  | "STORAGE" | "b062493"    | 3.6.0.      |
| "new-node3"    | 9779 | "ONLINE"  | "STORAGE" | "b062493"    | 3.6.0.      |
+----------------+------+-----------+-----------+--------------+-------------+
Got 3 rows (time spent 817/1421 us)

```
此方案还可用来做 snapshot 迁移数据，可以在源端创建 snapshot 后拷贝到目标端，后续按照以上替换 IP 步骤来操作。

作者：Henry

校对 & 编辑：清蒸

当你的集群节点的 IP 要更换时，可以通过以下步骤实现 IP 替换，并不需要重新导数据。

实践分享｜基于内核 2.x 和 3.x 的可行 IP 替换方案

![NebulaGraph v3.8.0 ](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-20-1.jpg)

本次 v3.8.0 版本的 NebulaGraph 主要在稳定性、性能、易用性等方面都进行了显著的改进和优化，同时修复了众多查询语句上的问题，提升了整体的用户体验。

### 特性功能
- 支持 **SINGLE SHORTEST PATH**。具体 pr 参见：#5664
- 支持 **INNER JOIN**。具体 pr 参见：#5664
- **ROUND()** 支持持舍入模式。具体 pr 参见：#5680
** 优化增强**
- 性能
  - **SHORTEST PATH** 支持 Limit 下推。具体 pr 参见：#5657
  - 优化部分逻辑避免 Follower 宕机后影响写性能。具体 pr 参见：#5673
  - 优化 Meta Service 中对 Session 的管理，减少高并发场景下的延时。具体 pr 参见：#5762
- 易用性
  - 减少删除 Graph Space 时的阻塞时间。具体 pr 参见：#5754
- 稳定性
  - 优化 **LEADER BALANCE** 算法，使得 Balance 更均匀。具体 pr 参见：#5670

  - 增加允许的最大语句条数的限制保护。具体 pr 参见：#5790

### 缺陷修复   

- 查询语言

  - 修复在多次执行 **LOOKUP** 语句时，结果不一致的问题。具体 pr 参见：#5662

  - 修复了 **UNION ALL** 报语法错误的问题。具体 pr 参见：#5674

  - 修复了 **SHORTEST PATH**、**ALL PATH**、**NOLOOP PATH** 场景下 Limit 结果错误、崩溃等的问题。具体 pr 参见：#5697、#5699、#5751、#5787、#5789

  - 修复在设置 Memory Tracker 的情况下，多次重复执行 **SHORTEST PATH** 崩溃的问题。具体 pr 参见：#5702

  - 修复了 Filter 的错误，避免 Graph Service 崩溃。具体 pr 参见：#5720

  - 修复在多变量的情况下，执行失败的问题。具体 pr 参见：#5734

  - 修复了 **MATCH SHORTEST PATH** 不支持自环检测的问题。具体 pr 参见：#5738

  - 修复在当过滤条件永远不成立时，部分场景崩溃的问题。具体 pr 参见：#5740

  - 修复了 **ROUND** 的崩溃问题。具体 pr 参见：#5773

  - 修复了 FIND PATH WITH PROP 一跳查询时，结果错误的问题。具体 pr 参见：#5759

  - 修复了** USE SPACE** + 查询时，性能变慢的问题。具体 pr 参见：#5793

  - 修复了 **FIND NOLOOP PATH** 未排除自环的问题。具体 pr 参见：#5805

- 其他

  - 修复了 **CLONE SPACE** 时的错误。具体 pr 参见：#3005、#5781
  - 修复了当存在索引时，**num_vertices_inserted** 监控指标无数据的问题。具体 pr 参见：#5756
  - 修复在进行查询和 Schema 的变更同时进行时概率出现崩溃的问题。具体 pr 参见：#5855

### 升级

具体步骤参考升级文档：[https://docs.nebula-graph.com.cn/3.8.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-comm/
 ](https://docs.nebula-graph.com.cn/3.8.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-comm/)

本次 v3.8.0 版本的 NebulaGraph 主要在稳定性、性能、易用性等方面都进行了显著的改进和优化，同时修复了众多查询语句上的问题，提升了整体的用户体验。

NebulaGraph v3.8.0 正式发布：全面提升稳定性与性能

![LDBC](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-04-23-1.jpg)

LDBC（Linked Data Benchmark Council）Social Network Benchmark，简称 LDBC SNB，是一种针对社交网络场景的评估图数据库性能的基准测试。

### LDBC 简介

除了 Social Network Benchmark，LDBC 旗下目前还有其他几种基准测试：Graphalytics Benchmark，Financial Benchmark 和 Semantic Publish Benchmark，分别针对图分析、金融和 RDF 的场景。Social Network Benchmark 是 LDBC 最早的提出的基准测试，已经成为国内外最主流的图数据库基准测试，在国内很多图数据库招标也会将 LDBC SNB 作为性能测试的一项。但需要说明的是，LDBC 本身作为一个非盈利组织，只提供官方审计。**不同图数据库可能受到运行环境以及基准测试的相关参数影响，因此测试结果的横向对比没有任何意义。**

LDBC SNB 主要包括三个主要部分：

1**.Data Generator**：这是一个数据生成工具，用于生成具有社交网络特性的大规模复杂数据。这些数据包括人、帖子、评论、地理位置、组织和其他一些社交网络的典型实体和关系。

2.**Interactive Workload**：主要针对 OLTP，模拟了用户在社交网络上的日常活动，例如发布帖子、添加好友、点赞等。读请求以查询以一到两跳为主，同时可能会伴随一些写请求。

3.**Business Intelligence Workload**：主要针对 OLAP，模拟了对社交网络数据进行深入分析，以全图查询为主。例如分析用户的社交行为、社区的形成和演变，以及其他一些需要复杂分析和大量数据处理的任务。

LDBC SNB 的论文里还提到了一个 SNB Algorithms，顾名思义主要是跑图算法的，如 PageRank、社区发现、广度搜索等。但论文是 2015 年发表的，当时描述这个场景还在起草中，目前已经将这部分移到了 Graphalytics Benchmark。

[https://discuss.nebula-graph.com.cn/t/topic/15080](https://discuss.nebula-graph.com.cn/t/topic/15080)

此外，想要运行 LDBC SNB 测试，还需要一个官方提供的 Driver。不同的数据库需要基于 Driver 的接口实现相应的 Connector，用来连接 Driver 和数据库。之后 Driver 会根据 Benchmark 的相关参数生成 Workload（这里可以理解为一系列的查询语句），并驱动待测数据库执行这些查询语句，最终得到性能测试结果。

整个 LDBC SNB 基准测试的流程如下，主要分成：**准备阶段、基准测试、结果输出**这三个阶段。

准备阶段主要执行数据生成，包括初次导入的全量数据，以及后续实时更新的数据。此外在官方审计中，还需要在 SF10 Dataset（在本文文末介绍了何为 SF）上进行 Validation，因此这一阶段也会生成用于校验的数据。

基准测试阶段会先在 SF10 Dataset 上进行 Validation，之后会在 SF30 或者 SF100 Dataset 进行性能测试。Validation 的过程就是在数据导入之后，由 Driver 根据之前准备阶段的一系列 query 和期望结果，对数据库的查询结果进行校验，以确保数据库的查询结果正确。Validation 的这个过程没有时间要求。而之后的性能测试分为导入、预热、性能测试，数据库可以有 30 分钟的预热时间，而在性能测试至少要持续两个小时，最终将测试结果汇总并输出。

![Validation](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-04-23-2.jpg)

由于篇幅限制，我们这一系列重点介绍 SNB Interactive Workload 相关内容。这一篇，我们主要会结合论文，介绍 SNB 的 Schema 以及数据生成，也就是准备阶段。

### LDBC SNB Schema 生成

说明：为了和 SNB 中的数据命名统一，本文相关名称我会用英文，所以读起来可能会有些怪怪的。为了降低理解成本，每个英文单词首次出现后面会跟随对应的中文注释讲解。

SNB 的数据主要是模拟了一个类似 Facebook 的社交网络。其中数据都是围绕 Person（人）构建而来，Person 之间会构成 Friendship（情谊）网络。每个 Person 可能会有若干 Forum（特定讨论区），Person 可以在 Forum 中下面发送若干 Post（帖子），其他 Person 可能会 likes（点赞）其中一些 Message（消息）。

以上这些元素的数据量主要会受 Person 和时间的影响：

- 有更多朋友的人会发送更多的评论或点赞

- 时间越长，会结交更多的朋友，评论或点赞数量也会上升

还有一部分数据不会随 Person 数量而变化，主要包括一些 Organization（组织，这里主要是学校）以及 Place（地方，这里主要是居住城市、国家等地理信息）。这部分数据会在数据生成时起一些作用，比如在同一时期在同一个学校上学的人更有可能称为朋友。

SNB 的完整 Schema 如下图所示：

![Schema](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-04-23-3.jpg)

大多数图数据库在进行测试时候，会将实体建模为点，而不同关系会建模为边。但这只是一个惯例，**SNB 的数据建模和实际数据库中的 Schema 可以不同，只要数据库能够完成相应 Workload 的查询即可**。

### LDBC SNB 数据生成 

SNB 的一个重要部分是 Data Generator（下文称为 DataGen），用来生成满足上面 Schema 的数据。Generator 生成的数据由以下三个参数决定：

- Person 的个数

- 模拟多少年的数据

- 从哪一年开始模拟

根据官方文档，DataGen 生成的数据有以下性质：

- 现实性：生成数据模拟了一个真实的社交网络。一方面，生成数据中的属性、基数、数据相关性和分布经过精心设置，从而能够模拟 Facebook 等真实社交网络。另一方面，其原始数据来自于 DBpedia，保证数据中的属性值真实且相关。

- 可扩展性：针对不同规模和预算的系统，DataGen 能够生成不同大小的数据集（GB 到 TB 级），此外 DataGen 可以在单机，或者是一个集群中完成数据生成。

- 确定性：无论用来生成数据的机器数量多少、机器配置是高还是低，DataGen 生成的数据都是确定且相同的。这一重要功能确保了任意一个数据系统都能使用相同的数据集，保证不同系统环境之间的测评比较公平且基准测试结果可重复。

- 易用性：DataGen 被设计得尽可能易于使用。

整个数据生成的流程图如下所示，我们会分解为几部分介绍：

![DataGen](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-04-23-4.jpg)

### 生成属性分布

第一步是初始化。DataGen 使用的原始数据来自于 DBpedia，针对每一个属性，DataGen 会根据以下方面决定属性的分布：

- 有多少种可能的属性值

- 每一种属性值出现的概率

最终将属性的分布情况作为资源文件以及 DataGen 的参数保存下来。

### 生成 Person 和 Friendship

前面也提到过，SNB 的 Schema 的核心是 Person，这也体现在数据生成过程中。接下来 DataGen 就会生成所有 Person，以及 Person 中一部分后续操作所需要的信息，比如每个 Person 有多少 Friendship（这个值非常重要，其分布满足 Power law（幂定律）），Person 所就读的大学，Person 所就职的公司等。

接下来，DataGen 会创建每个 Person 的 Friendship 关系（即流程图中的 knows）。和真实社交网络一样，有相同兴趣或者行为的人，很有可能会连接在一起。为了模拟这样的社交网络，SNB 在生成 Friendship 时会考虑以下三个维度：

- Person 所就读的大学，就读时间，以及大学所在城市

- Person 的兴趣

- 每个 Person 会生成一个随机值，随机值越相近代表其越类似（这是为了模拟不是所有朋友都是通过大学和兴趣结交的）

三个维度分别占每个 Person 的 Friendship 关系权重的 45%，45% 和 10%，也就将 Person 之间建边的过程分成了三个子步骤。

DataGen 会依次根据三个维度将所有 Person 进行排序（每次只按一个维度进行排序），然后将排序过后的 Person 切分为不相交的多个部分，分发给不同 Worker 进程。即便是切分之后，每个 Worker 线程负责的 Person 可能也可能超过内存大小。因此，Worker 线程会维护一个滑动窗口，滑动窗口内的 Person 之间建立 Friendship 关系的概率满足几何分布。

如下图所示：

![Friendship](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-04-23-5.jpg)

假设现在根据就读大学这个维度进行了排序，得到了一个 Person 有序序列。之后 Worker 就会维护一个滑动窗口，每次为滑动窗口最左侧的人生成 Friendship 关系（上图当前是 P2），滑动窗口内的其他人和窗口第一个人建立 Friendship 的比例满足几何分布。

直到滑动窗口的第一个人建立了足够多的 Friendship 之后，滑动窗口的起点会移到下一个人。

这里没有深究滑动窗口的大小、几何分布的参数甚至是随机生成器的参数，不知道在出现滑动窗口内无法生成足够多 Friendship 关系时，DataGen 如何处理。

将三个维度都经过排序、分发、按滑动窗口建边之后，DataGen 就进入了下一阶段。

### 生成社交活动

生成完 Person 和 Friendship 之后，DataGen 就开始生成每个 Person 的社交活动，包括 Forum，Post 和 Comment。这部分数据也有一些相关性存在：

1.有越多 Friendship 的 Person 在社交网络上会越活跃

2.每个 Person 更可能在自己感兴趣或者就读大学相关的 Forum 进行 Post 或者 Comment

3.社交活动和时间是有相关性的，比如接近世界杯，足球相关的讨论就会激增

### 最终输出

经过以上步骤之后，DataGen 完成了数据生成，模拟的社交网络图会分成两部分进行输出：

- Dataset：90% 的数据用于初始导入

- Update Streams：10% 的数据用于后续实时更新

除此之外，还会生成后续 Workload 中请求的参数（主要是起点）。关于参数生成我们会在下一篇详细解释，这里简单描述一下 SNB 的读请求 Workload。Interactive Workload 主要的查询希望在一秒以内得到查询结果，所有读 query 都是从图中的一个点出发，获取很小一部分的子图信息。另外，因不同起点的出入度不同，基本上也就决定了这次读请求会访问的数据量。

为了测试不同系统和场景，SNB 定义了**比例因子（Scale Factor，即所谓的 SF）用来控制最终生成的数据量大小**。比如，SF1 原始数据大小为 1 GB，同理 SF0.1 和 SF300 的大小为 100 MB 和 300 GB。不同比例因子的各个类型的点边数据量如下表所示：

![Scale Factor](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-04-23-6.jpg)

最终生成的 Dataset 分为两大类：Static 和 Dynamic，格式都是 CSV。根据 DataGen 配置的线程数量大小，最终生成的数据也会分为多个分片。Static 包含 Organization、Place、Tag 等，都是基于 DBpedia 生成的静态数据，其数量不会随着比例因子变化而变化。换而言之，这部分数据与 Person 的个数无关。而 Dynamic 部分主要包括 Person、knows（即前面数据生成部分描述的 Friendship）、Forum、Post 和 Comment 等。

而 Update Streams 中包含了所有更新的操作，主要就是模拟实时注册新用户、评论、点赞、加好友等等行为。

## 参考文献  

到这里准备阶段大概就介绍完了，在准备阶段最终生成的请求参数部分我们会在下一篇讲述 Workload 时再展开。

- ldbc-snb-interactive-sigmod-2015.pdf (ldbcouncil.org)

- The LDBC Social Network Benchmark Specification


## 关于 NebulaGraph  

NebulaGraph 是一款开源的分布式图数据库，自 2019 年开源以来，先后被美团、京东、360 数科、快手、众安金融等多家企业采用，应用在智能推荐、金融风控、数据治理、知识图谱等等应用场景。GitHub 地址：[https://github.com/vesoft-inc/nebula](https://github.com/vesoft-inc/nebula)

DataGen 会依次根据三个维度将所有 Person 进行排序（每次只按一个维度进行排序），然后将排序过后的 Person 切分为不相交的多个部分，分发给不同 Worker 进程。

图数据库基准测试 LDBC SNB 系列讲解：数据测评公平、结果可重复的秘密

![Workload](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-04-17-1.webp.jpg)

继上文的 LDBC 数据生成🔗之后，在这一篇我们主要介绍 SNB Workload 里的各个 Query 是如何生成的，以及在性能测试中 Driver 是如何执行 Workload。

**Workload**

在基准测试的准备阶段之后，总共生成了三类数据：
- **Dataset**：用于初始导入的数据
- **Update Streams**：用于 Driver 在性能测试阶段实时更新
- **Parameters**：用于 Driver 在性能测试阶段读请求的参数

### 写请求 Write Query

由于 SNB 生成的数据非常复杂，因此在性能测试阶段不可能通过 SNB Driver 实时生成更新请求，因此**实时更新的数据实际是由 DataGen 来生成的**。我们在上一篇也提到过，使用 LDBC 时 DataGen 需要指定生成多长时间的数据，以及社交活动是从哪一年开始。DataGen 会根据时间戳将所有数据进行切分，将 90% 数据作为 Dataset，剩下的 10% 数据作为 Update Streams 用于后续更新的写请求。

对于所有写请求，DataGen 都会将这次写请求（Update Query）调度执行的时间、相关更新的参数生成到一个 JSON 中。（至于为什么需要指定 Query 调度时间，我们后续会解释）

### 读请求 Read Query

SNB 的读请求分为两大类：14 个 Complex read-only queries 以及 7 个 Short read-only queries。

Complex 读请求都是以一个给定 Person 出发，查询一跳或者两跳子图内的相关信息。比如 Interactive Complex 9（简称 IC9）的查询 Pattern 如下：给定一个起始的人，查询这个人的朋友或者朋友的朋友创建的最近 20 条消息。如下图所示：

![Read Query](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-04-17-2.webp.jpg)
图注：Interactive / complex / 9

Short 读请求分为两大类：一类是给定一个人，查询这个人的姓名、年龄等信息，或者是这个人的朋友以及这些朋友发送的消息。另一类则是给定一个消息，返回这条消息是的发送者以及发送者的相关信息。类似下图这样：

![Short ](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/204-04-17-3.webp.jpg)
图注：Interactive / short / 1

完整的请求描述可以参见**《The LDBC Social Network Benchmark Specification》** 的 6.1 和 6.2 章节，这里就不展开了。

### 请求参数

除了 Dataset 和 Update Streams 之外，DataGen 还会生成不同读请求的参数（比如上面 IC9 的起点 PersonId）。为了保证性能测试的结果能够稳定的衡量数据库的性能，SNB 保证生成读请求的参数满足以下性质：

1.查询时间有上限：Complex Read 和 Short Read 请求所涉及的数据会因为起点不同而不同，但从宏观上看，其查询的子图都是有限的，因此其查询时间也会有一个合理的范围。

2.查询执行时间满足稳定的分布：同一个读请求的各个起点不同，查询数据量会不一样，但最终查询时间分布是稳定的。

3.逻辑计划相同：给定一个查询，无论起点如何不同，最终经过优化器优化之后生成的逻辑查询计划是相同的。这条性质保证每一个查询，能够稳定测试到图数据库中的一些技术难点（比如大量 JOIN、基数估计等）。

其中前两条还比较好理解，但最后一条可能做到吗？我们都知道一个优秀的优化器会根据查询参数决定实际执行时的 JOIN 顺序。即便对于相同的查询 Pattern，由于查询参数不同，最终的执行计划也会千变万化。我们看下** DataGen 是如何筛选参数，使同一个查询最终采用相同的查询计划。**

首先，我们都知道查询数据量和查询时间是强相关的。对于每一个查询 Pattern，LDBC 在设计时都会有一个理想执行计划，在这个理想执行计划中，其数据量是可以通过起点预先计算出来的。

比如 Complex 2：

![Complex 2](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-04-17-4.webp.jpg)

获取给定某个人的朋友发送的最近 20 个消息，其理想查询计划如下所示。

![Parameter-Count table](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-04-17-5.webp.jpg)

对于这个理想执行计划，我们可以预处理得到每个起点的 JOIN 的中间结果行数。比如对于 PersonID=1542 的起点，两次 JOIN 的中间结果的数量分别为 60 和 99。最终，对于每个 Query，会生成一个起点和中间 JOIN 结果行数的表，称为 Parameter-Count table。

**这个 Parameter-Count table 是由 DataGen 在生成数据过程中一起生成的。**有了这张表，挑选参数的问题就变成了在这张表中挑选若干最相近的行。在这一步中采用的方式是贪心的启发式搜索：首先根据 Join1 中间结果数量，挑选最相近的若干行（Join1 中值为 60 的几行），然后在这些行中再根据 Join2 的中间结果数量进行挑选（得到 Join2 值为 99、102、103 的几行），最终筛选出来的 PersonID 为1542、1673、7511。

这里存疑的是，按理来说应该先确定需要挑选参数的个数 k，然后再在 Parameter-Count table 进行筛选，否则按论文所说方法，可能会导致最终挑选的行数小于 k。这里没有深究，但整体思路是合理的。

通过上述步骤，对于每一个 Query 类型，都会挑选出来若干个最相近的参数，从而尽可能使得查询计划相同。不过还剩一个问题，如何确定每个查询需要多少个参数，也就是不同查询的数量呢？

### Query Mix

首先，LDBC SNB Interactive Workload 期望数据库在性能测试过程中，**Update Query、Complex Query 和 Short Query **的执行时间比例依次是 **10%、50% 和 40%**。这个比例一方面是为了模拟真实的社交网络负载，一般来说读请求会远多于写请求，另外这个负载也要能够真实反映数据库的性能。

尽管在上一步中，DataGen 保证了同一个查询中的不同参数的执行时间相近。但不同查询的数据量和执行数据有巨大的差别。因此为了能够避免某一个类型的查询对最终测试结果起决定性作用，不同类型查询的数量需要精心的设计。

**SNB Interactive Workload 主要认为 Complex Read Query 应该主导是性能测试分数**。Complex Read Query 的数量是由 Update Query 的数量决定的，如下表所示：

![Complex Read Query](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-04-17-6.webp.jpg)

比如在 SF100 中每执行 527 个 Update Query 之后应该执行一次 Complex Read Query 9。前面提过，每个 Update Query 的调度时间由 DataGen 已经决定了，因此每一个 Complex Read 的调度时间也就确定了。**这里可以暂时将调度时间理解为相对于性能测试开始时间的一个相对时间，这个相对时间实际还会受到 SNB Driver 相关参数的影响。**之所以是调度时间而不是执行时间的原因在于待测数据库可能已经满负载或者没有响应，导致某个 Query 可能已经到了调度时间，但无法及时执行 Query。

这里就可以理解为什么 SNB 号称其测试结果可重复，关键之处就是 DataGen 生成的数据是确定性的。一旦 Update Query 调度时间确定，也就确定了 Complex Read Query 的调度时间，进而确保其性能测试结果可重复。了解这一点对于后续理解性能测试的结果以及 SNB Driver 的相关参数是至关重要的。

而 Short Query 会被穿插在每一个 Complex Query 之后。前面提到过 Short Query 分为两大类，查询人的相关信息以及查询消息的相关信息。准确来说，不同类型的 Complex Query 可能会返回不同信息，根据 Complex Query 的查询结果，后续会从 Short Query 中挑选一类，并把 Complex Read 的结果（比如 Person 或者 Message 的标识符）作为 Short Query 的参数进行查询。

一个 Short Query 被调度之后，后续有可能会调度另一个 Short Query，每次概率逐渐降低。即一个 Complex Query 之后，可能调度一连串 Short Query（论文中称为 Short Read Random Walk）。不同的 Query 后面可能触发的 Short Query 类型不同，如下表所示，比如 IC10 之后就只能触发 IS1、IS2 和 IS3。
![Short Query](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-04-17-7.webp.jpg)

图注：IC 为 Interactive Complex query 的缩写，IS 为 Interactive Short query 的缩写

和 Complex Query 不同的时，Short Query 的调度时间是由 Driver 根据它所依赖的 Complex Read 的完成时间所动态决定的。但触发多少个 Short Query 就是由上面说的概率决定，而所有性能测试过程中使用的随机生成器是相同的，综上所述整个基准测试过程中所有 Query 的比例和顺序是确定的。

### Driver

Driver 依赖 DataGen 生成的 Dataset、Update Streams 和 Parameters，它主要能完成两个任务：

- Validate：校验数据库的正确性
- Benchmark：验证数据库的性能

Validate 比较简单，根据 Update Streams 和 Parameters，生成若干用于校验的参数，**为了验证数据库的结果正确性，Validate 依赖于确定的顺序执行查询，因此只能单线程执行。**Driver 最终会在数据库输出是否通过验证的结果。

Benchmark 则是根据 Dataset、Update Streams 和 Parameters 以及相关配置，生成确定的 Workload（即一个 Operation 序列，其中包含 Query 和对应调度时间）。根据调度时间，按顺序发送给待测数据库，同时保存其调度时间、开始执行时间和结束执行时间，最终输出性能报告。

Driver 主要由 Runtime、Workload、Database Connector、Report 这几部分组成。

### Runtime & Workload

无论最终性能测试在什么环境、待测图数据库是什么，只要 Driver 的输入（数据和配置）相同，其生成的 Workload 就是相同的。为了得到最高的吞吐量，一般会把 Workload 拆成多个 Stream。对于图来说，多个操作是有前后依赖关系的，比如好友存在才能添加好友关系。因此，Driver 支持由多个线程来执行这个序列（由 thread_count 参数控制），但也需要保证即便有多个线程来执行，操作之前的依赖关系没有被破坏，仍然满足 DataGen 生成的调度时间关系。这部分原理就不展开介绍，感兴趣的可以阅读论文中的相关部分。

Workload 中的每个 Operation 包括以下信息：

- **Query 类型**

- **Query 参数**

- **调度时间**

- **期望结果（只在 Validate 中使用）**

前面提到过所有 Update Query 和 Complex Query 的调度时间都是 DataGen 预先确定好的，Driver 会根据调度时间通过 Database Connector，把 Query 发送给数据库执行。显然，如果这些调度时间都是一个固定值，我们是无法获知数据库的真实性能的。

在 Driver 中有一个参数 time_compression_ratio（默认为 1），可以在时间维度上拉伸或者压缩整个 Workload，比如 time_compression_ratio 为 2.0 代表这个 benchmark 的运行持续时间会变成默认的两倍，也就是将 Query 之间的间隔时间变为原来的两倍。同理，time_compression_ratio 为 0.1 代表 Driver 发送 Query 的速度是默认情况下的 10 倍。简而言之：
- time_compression_ratio > 1，比默认慢
- time_compression_ratio < 1，比默认快

注意，修改 time_compression_ratio 不会影响 Query 序列中各个类型 Query 的比例、Query 的参数和执行顺序。

### Database Connector

为了将数据库对接至 SNB，厂商需要实现对应的 Database Connector。其主要任务就是对接目标数据库：

1.将 Driver 框架的 Query 类型和参数，转换为目标图数据库的 Query
2.将 Query 通过 Database Connector 发送给目标图数据库
这部分都只需要实现 Driver 的若干接口即可，可以参考：[https://github.com/ldbc/ldbc_snb_interactive_v1_driver](https://github.com/ldbc/ldbc_snb_interactive_v1_driver)以及相关集成文档。

### Driver Configuration

Benchmark 的主要目的就是在保证大于 95% 的及时率前提下，得到最优的 time_compression_ratio（越小代表性能越高）。Operation 如果在期望调度时间过后的 1 秒之内被 Driver 调度，就认为是及时的：

actual_start_time − scheduled_start_time < 1 second

此外，一次有效的 Benchmark 需要至少需要测试两个小时（预热的半个小时期间，性能是不计入在结果之内）。

![Benchmark](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-04-17-7.webp.jpg)

为了运行一次有效的 Benchmark，Driver 有几个重要的参数需要调整：

- time_compression_ratio：调整 Workload 的执行速度，准确说是期望执行速度
- operation_count：Driver 总共需要生成多少个 Operation，配合 - time_compression_ratio 修改，以保证 Benchmark 的时长
- thread_count：执行 Operation 的线程池大小，根据待测数据库的性能，可能也需要调整并发执行 Query 的数量

### Report

最终 Driver 会生成如下性能指标：
- Start Time：开始时间，第一个 Operation 开始时间
- Finish Time：完成时间，最后一个 Operation 完成时间
- Total Run Time：运行时间，Finish Time 和 Start Time 的差值
- Total Operation Count：Operation 总数，总共执行了多少个 Operation

系统的 QPS 可以通过 Total Operation Count / Total Run Time 得到。

对于每个类型的 Query，Driver 也会输出每个 Query 的总数，执行时间的平均值、中位数、P95、P99等、以及调度时间的延迟分布等。

![Query](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-04-17-9.webp.jpg)

图注：LDBC 报告示意图


**参考文献**

有关 LDBC SNB Interactive 的介绍基本就到这了，后续可能还会总结一下这个基准测试的一些设计思想。另外我们自己系统在测试过程中，也出现了一些因为对 SNB 本身不够理解而当时看来十分诡异的现象，这也是花时间总结这几篇文章的初衷。

- ldbc-snb-interactive-sigmod-2015.pdf (ldbcouncil.org)
- The LDBC Social Network Benchmark Specification
- GitHub - ldbc/ldbc_snb_interactive_v1_driver: Driver for the LDBC SNB Interactive workload

## 关于 NebulaGraph  

NebulaGraph 是一款开源的分布式图数据库，自 2019 年开源以来，先后被美团、京东、360 数科、快手、众安金融等多家企业采用，应用在智能推荐、金融风控、数据治理、知识图谱等等应用场景。GitHub 地址：[https://github.com/vesoft-inc/nebula](https://github.com/vesoft-inc/nebula)

无论最终性能测试在什么环境、待测图数据库是什么，只要 Driver 的输入（数据和配置）相同，其生成的 Workload 就是相同的。为了得到最高的吞吐量，一般会把 Workload 拆成多个 Stream。对于图来说，多个操作是有前后依赖关系的，比如好友存在才能添加好友关系。