Article

图数据库NebulaGraph

更新于：2026-07-16

第一章：NebulaGraph 概述

1.1 什么是 NebulaGraph

概念名称	说明	注意事项
NebulaGraph	一个开源的分布式原生图数据库，专为处理超大规模图数据（百亿点、千亿边）设计，支持毫秒级查询响应。	不是关系型数据库的扩展，而是专为图结构优化的存储与计算系统。
原生图数据库	数据模型直接以”点（Vertex）“和”边（Edge）“为核心，存储和查询均围绕图结构进行，无需 JOIN 操作。	区别于将图数据存入关系库再通过应用层构建图逻辑的方案。
开源协议	采用 Apache 2.0 许可证，允许商业使用、修改和分发。	社区版功能完整，企业版提供额外运维与安全特性。
分布式架构	支持水平扩展，数据自动分片（Partition），无单点瓶颈。	需合理规划 Partition 数量与副本数以平衡性能与容灾。

1.2 核心组件与架构

概念名称	说明	注意事项
Meta Service	元数据服务，负责存储图空间（Space）、Schema（Tag/Edge Type）、用户权限、集群拓扑等元信息。由 Raft 协议保证高可用。	默认端口 9559；生产环境建议部署奇数个 Meta 节点（如 3 或 5）。
Storage Service	存储服务，负责持久化点、边及其属性数据。数据按 Partition 分片，支持多副本，使用 Raft 实现一致性。	默认端口 9779；磁盘 I/O 和 SSD 性能直接影响查询速度。
Graph Service	计算服务，接收客户端 nGQL 查询，解析并生成执行计划，向 Storage Service 请求数据，最终返回结果。无状态，可弹性扩缩容。	默认端口 9669；CPU 密集型，建议部署在高性能计算节点。
Client / Console	客户端工具，如 nebula-console（命令行）、Nebula Studio（Web UI）、各语言 SDK，用于连接和操作数据库。	nebula-console 是最基础的调试与管理工具，适合学习和脚本化操作。
架构通信方式	各服务间通过 Thrift RPC 通信；客户端通过 Graph Service 接入，不直连 Storage 或 Meta。	网络延迟和带宽对跨机房部署影响显著，建议同地域部署。

1.3 适用场景与优势

概念名称	说明	注意事项
适用场景 - 社交网络	快速查询好友关系、六度人脉、共同好友等复杂关联分析。	关系深度超过 5 层时，需注意查询性能与内存消耗。
适用场景 - 金融风控	识别洗钱团伙、欺诈环路、资金流向追踪，利用图算法发现异常模式。	需结合实时数据流（如 Kafka）实现动态图更新。
适用场景 - 知识图谱	构建实体-关系网络，支持语义搜索、推理与推荐。	Schema 设计需提前规划好实体类型与关系类型。
适用场景 - IoT/设备图	表示设备拓扑、依赖关系、故障传播路径分析。	边方向性（有向图）对路径分析至关重要。
核心优势 - 高性能	列式存储 + 向量化执行 + 异步 IO，支持百亿级点边毫秒级遍历。	性能依赖良好 Schema 设计与索引策略。
核心优势 - 强扩展性	无中心架构，Storage 和 Graph 服务均可独立横向扩展。	扩容后需 rebalance 数据（可通过 `BALANCE` 命令触发）。
核心优势 - 类 SQL 语法	使用 nGQL（Nebula Graph Query Language），语法接近 SQL，降低学习成本。	nGQL 不完全兼容 Cypher，迁移需重写查询逻辑。
核心优势 - 多语言支持	提供 Java、Python、Go、Rust 等官方客户端 SDK。	社区 SDK 更新频率可能低于核心引擎，建议关注 GitHub 仓库。

第二章：环境搭建与部署

2.1 单机部署（Docker / 本地编译）

步骤名称	操作细节	注意事项
使用 Docker 部署	1. 安装 Docker 和 Docker Compose 2. 下载官方 docker-compose.yaml： `bash curl -O https://raw.githubusercontent.com/vesoft-inc/nebula-docker-compose/master/docker-compose.yaml` 适用于快速体验和开发测试；默认包含所有核心服务（Meta/Storage/Graph）。 3. 启动服务： `bash docker-compose up -d`
本地源码编译部署	1. 克隆源码： `bash git clone --branch v3.6.0 https://github.com/vesoft-inc/nebula.git` 2. 安装依赖（CMake ≥ 3.14, GCC ≥ 7.5） 3. 编译： `bash cd nebula && mkdir build && cd build cmake .. -DENABLE_TESTING=OFF -DCMAKE_BUILD_TYPE=Release make -j4` 4. 安装并配置路径	编译耗时较长（30+ 分钟），需充足内存（建议 ≥16GB）；适合深度定制或贡献代码。
配置文件位置	Docker 方式：配置在容器内 /usr/local/nebula/etc/ 源码编译：默认安装到 build/install/ 目录下	修改配置后需重启对应服务容器或进程。
默认端口说明	Graph Service: 9669 Meta Service: 9559 Storage Service: 9779	若端口被占用，需修改 docker-compose.yaml 或 *.conf 文件。

2.2 集群部署（多节点）

步骤名称	操作细节	注意事项
规划集群拓扑	至少 3 台机器（可混合部署或分离部署）： - Meta 节点：3 个（奇数，保证 Raft 选主） - Storage 节点：≥3 个（数据分片副本） - Graph 节点：≥1 个（无状态，按需扩展）	不建议单机模拟多节点用于生产环境。
准备每台机器环境	所有节点安装相同版本 Nebula（推荐使用 RPM/DEB 包或统一编译）关闭防火墙或开放端口：9559, 9669, 9779, 19559, 19669, 19779（内部通信端口为服务端口 + 10000）	时间同步（NTP）必须开启，否则 Raft 可能异常。
配置 Meta 服务	在每台 Meta 节点的 nebula-metad.conf 中设置： `--meta_server_addrs=ip1:9559,ip2:9559,ip3:9559` `--local_ip=本机IP` `--ws_ip=本机IP`	meta_server_addrs 必须一致且包含自身。
配置 Storage 服务	在每台 Storage 节点的 nebula-storaged.conf 中设置： `--meta_server_addrs=ip1:9559,ip2:9559,ip3:9559` `--local_ip=本机IP`	Storage 启动前 Meta 必须已正常运行。
配置 Graph 服务	在每台 Graph 节点的 nebula-graphd.conf 中设置： `--meta_server_addrs=ip1:9559,ip2:9559,ip3:9559`	Graph 服务启动不依赖 Storage 是否就绪。
启动服务顺序	1. 先启动所有 Meta 节点 2. 再启动所有 Storage 节点 3. 最后启动 Graph 节点	顺序错误可能导致注册失败或数据不一致。

2.3 启动与验证服务状态

步骤名称	操作细节	注意事项
启动服务（Docker）	`bash docker-compose start` 或 `bash docker-compose up -d`	使用 `docker-compose ps` 查看容器状态。
启动服务（本地二进制）	进入安装目录 install/，执行： `bash ./scripts/nebula.service start all` 或分别启动： `bash ./bin/nebula-metad --flagfile etc/nebula-metad.conf &` `bash ./bin/nebula-storaged --flagfile etc/nebula-storaged.conf &` `bash ./bin/nebula-graphd --flagfile etc/nebula-graphd.conf &`	确保配置文件路径正确；后台运行需加 &。
验证服务是否运行	`bash ./scripts/nebula.service status all` 或检查进程：`bash ps aux \| grep nebula-`	若某服务未启动，查看对应日志（logs/ 目录下）。
使用 nebula-console 连接	安装 console： `bash pip install nebula3-python` 连接命令： `bash nebula-console -addr 127.0.0.1 -port 9669 -u root -p nebula`	默认用户名 root，密码 nebula（可修改）。
执行简单查询验证功能	在 console 中执行： `ngql SHOW HOSTS;` 预期返回所有 Storage 节点状态（ONLINE）	若显示 OFFLINE，检查 Storage 与 Meta 网络连通性及配置。
查看日志定位问题	日志默认位于 logs/ 目录： - metad.ERROR / metad.INFO - storaged.ERROR - graphd.ERROR	ERROR 日志通常包含关键故障信息；INFO 日志可用于跟踪请求流程。

第三章：命令行工具 nebula-console 使用

3.1 安装与连接数据库

步骤名称	操作细节	注意事项
安装 nebula-console（Python 版）	执行命令： `bash pip3 install nebula3-python` 安装后可使用 nebula-console 命令（部分版本需通过 -m nebula3.console 调用）	需 Python ≥ 3.6；建议使用虚拟环境避免依赖冲突。
从源码安装 console	克隆仓库： `bash git clone https://github.com/vesoft-inc/nebula-console.git` `bash cd nebula-console go build .` 生成二进制文件 nebula-console	需 Go ≥ 1.18；适用于定制化需求或最新功能体验。
连接本地 NebulaGraph	`bash nebula-console -addr 127.0.0.1 -port 9669 -u root -p nebula`	默认用户名为 root，密码为 nebula（可在部署时修改）。
连接远程集群	`bash nebula-console -addr <graph_host_ip> -port 9669 -u <username> -p <password>`	确保目标主机 9669 端口开放且网络可达。
指定图空间自动 USE	`bash nebula-console -addr 127.0.0.1 -port 9669 -u root -p nebula -space my_space`	若指定的 space 不存在，连接会失败。
查看帮助信息	`bash nebula-console --help`	可查看所有支持的连接参数（如 timeout、ssl 等）。

3.2 基本交互命令

步骤名称	操作细节	注意事项
查看当前连接信息	在 console 中输入： `ngql :server_status`	显示 Graph 服务地址、版本、连接状态。
列出所有图空间	`ngql SHOW SPACES;`	需有相应权限；返回空间名称列表。
切换图空间	`ngql USE my_space;`	必须先创建 space 才能 USE；后续操作均在此 space 内生效。
查看 Schema 定义	`ngql SHOW TAGS;` `ngql SHOW EDGES;` `ngql DESCRIBE TAG user;` `ngql DESCRIBE EDGE follow;`	DESCRIBE 可查看 Tag/Edge 的属性字段及类型。
执行简单查询	`ngql GO FROM "player100" OVER follow YIELD dst(edge);`	查询前需确保数据已插入；点 ID 默认为字符串类型（除非指定 int）。
退出 console	`ngql EXIT;` 或按 Ctrl+D	会自动断开连接并退出程序。
清屏	`ngql :clear`	仅清除终端显示，不影响历史命令。
显示执行耗时	默认开启；每条语句执行后显示 Time used: X.XXX ms	可用于性能初步评估。

3.3 脚本执行与批处理

步骤名称	操作细节	注意事项
执行单条 nGQL 命令（非交互）	`bash nebula-console -addr 127.0.0.1 -port 9669 -u root -p nebula -e "SHOW HOSTS;"`	适合集成到 Shell 脚本或 CI/CD 流程中。
执行 SQL 脚本文件	准备文件 init.ngql，内容如： `ngql CREATE SPACE test(vid_type=fixed_string(30)); USE test; CREATE TAG person(name string, age int);` 执行： `bash nebula-console -addr 127.0.0.1 -port 9669 -u root -p nebula -f init.ngql`	文件编码建议 UTF-8；语句间需用分号 `;` 分隔。
启用 CSV 输出模式	`bash nebula-console -addr 127.0.0.1 -port 9669 -u root -p nebula -e "GO FROM 'A' OVER rel YIELD src(edge), dst(edge)" --format csv`	便于导入 Excel 或其他分析工具；默认为 table 格式。
设置连接超时	`bash nebula-console -addr 127.0.0.1 -port 9669 -u root -p nebula -timeout 60000 -e "MATCH (v) RETURN v LIMIT 1"`	单位为毫秒；长查询需适当增大超时值。
批量导入初始化数据	结合 -f 参数执行包含多条 INSERT 语句的脚本： `ngql INSERT VERTEX person(name, age) VALUES "tom":("Tom", 25); INSERT EDGE follow(degree) VALUES "tom"->"jerry":(85);`	大批量数据建议使用 Nebula Exchange 或 Spark Writer，而非 console。
错误处理与退出码	若脚本中某条语句失败，默认继续执行后续语句；可通过 shell 判断 `$?` 获取退出码（0 表示全部成功）	生产脚本建议加入错误检查逻辑。

第四章：图模型基础

4.1 Tag（点标签）

概念名称	说明	注意事项
Tag 定义	Tag 是点（Vertex）的类型标签，用于对点进行分类。一个点可以拥有多个 Tag（如 “user” 和 “employee”）。	类似于关系数据库中的”表”，但一个点可属于多个 Tag。
Tag 作用	定义点的属性结构（Property Schema），便于按类型查询和管理数据。	查询时可通过 Tag 快速过滤点集，提升性能。
创建 Tag 语法	`ngql CREATE TAG <tag_name> (<prop_name> <data_type>, ...);` 例如： `ngql CREATE TAG person(name string, age int);`	Tag 名称在 Space 内必须唯一；属性名也需唯一。
修改 Tag	支持添加属性（`ALTER TAG ... ADD`）、修改属性类型（有限支持）、删除属性（`DROP`）	不支持直接重命名 Tag；删除属性后历史数据仍保留但不可访问。
删除 Tag	`ngql DROP TAG <tag_name>;`	删除前需确保无点使用该 Tag，否则报错。
查看 Tag	`ngql SHOW TAGS;` `ngql DESCRIBE TAG <tag_name>;`	DESCRIBE 可查看属性名、类型、是否为空等信息。

4.2 Edge Type（边类型）

概念名称	说明	注意事项
Edge Type 定义	Edge Type 是边（Edge）的类型标识，用于区分不同关系（如 “follow”、“knows”）。每条边必须且只能属于一种 Edge Type。	类似于关系数据库中的”外键关系类型”，但支持多属性。
边的方向性	NebulaGraph 中的边默认是有向的（从 src 到 dst），但可通过反向遍历模拟无向图。	查询时需明确方向（`->` 或 `<-`）。
创建 Edge Type	`ngql CREATE EDGE <edge_type> (<prop_name> <data_type>, ...);` 例如： `ngql CREATE EDGE follow(degree int);`	Edge Type 名称在 Space 内唯一；支持 TTL（生存时间）设置。
修改 Edge Type	支持 `ALTER EDGE ... ADD/DROP` 属性	不能修改已有属性的数据类型；不能更改 Edge Type 名称。
删除 Edge Type	`ngql DROP EDGE <edge_type>;`	删除前需清空所有该类型的边，否则报错。
查看 Edge Type	`ngql SHOW EDGES;` `ngql DESCRIBE EDGE <edge_type>;`	DESCRIBE 显示属性定义，不显示边实例数据。

4.3 Property（属性）

概念名称	说明	注意事项
属性定义	Property 是 Tag 或 Edge Type 中的字段，用于存储点或边的附加信息（如 name、age、timestamp）。	属性必须在 Schema 中预先定义，不支持动态添加未声明字段。
支持的数据类型	基本类型：`bool`, `int`, `float`, `double`, `string`, `date`, `time`, `datetime` 复合类型：`fixed_string(N)`, `geography`（point/linestring/polygon）	`fixed_string(N)` 要求 N ≤ 255；`string` 无长度限制但影响性能。
属性约束	所有属性默认允许 NULL；NebulaGraph 不支持 NOT NULL、DEFAULT、UNIQUE 等约束。	应用层需自行保证数据完整性。
属性更新	使用 `UPDATE VERTEX/EDGE` 或 `INSERT ... ON DUPLICATE KEY UPDATE` 修改属性值	更新操作需指定完整的 VID 和边的 src/dst + rank。
属性索引	可对属性创建索引以加速 WHERE 条件查询	索引需单独创建（见第七章）；写入性能会略有下降。
多版本属性	NebulaGraph 支持同一边在不同 rank 下存在多条记录（rank 为 int64），实现属性时序版本	默认 rank = 0；插入时可显式指定 RANK `<int>`。

4.4 Space（图空间）

概念名称	说明	注意事项
Space 定义	Space 是 NebulaGraph 中的逻辑数据库容器，包含独立的 Schema（Tags/Edges）和数据，类似 MySQL 中的 database。	不同 Space 之间完全隔离，无法跨 Space 查询。
创建 Space	`ngql CREATE SPACE <space_name> (<options>);` 常用选项： - partition_num：分片数（默认 100） - replica_factor：副本数（默认 1） - vid_type：点 ID 类型（fixed_string(N) 或 int64）	生产环境建议 replica_factor ≥ 3；vid_type 一旦设定不可更改。
使用 Space	`ngql USE <space_name>;`	所有 DDL/DML 操作必须在 USE 某个 Space 后执行。
查看 Space	`ngql SHOW SPACES;` `ngql DESCRIBE SPACE <space_name>;`	DESCRIBE 显示 partition_num、replica_factor、vid_type 等配置。
删除 Space	`ngql DROP SPACE <space_name>;`	删除后所有数据和 Schema 永久丢失，不可恢复。
Space 与性能	partition_num 影响数据分布和并发能力；过小导致热点，过大增加元数据开销	建议初始值 = 集群 Storage 节点数 × 10；后续可通过 BALANCE 调整。

第五章：nGQL 基础语法

5.1 图空间管理（CREATE/USE/DROP SPACE）

方法名称	语法	用途	代码示例	注意事项
CREATE SPACE	`ngql CREATE SPACE [IF NOT EXISTS] <space_name> (<option_list>);` option_list: `partition_num = N, replica_factor = M, vid_type = {fixed_string(N) \| int64}`	创建新的图空间	`ngql CREATE SPACE my_space(partition_num=10, replica_factor=3, vid_type=fixed_string(32));`	vid_type 一旦设定不可修改；replica_factor 必须为奇数（建议 3）以支持容灾。
USE SPACE	`ngql USE <space_name>;`	切换当前操作的图空间	`ngql USE my_space;`	所有后续 DDL/DML 操作均在此 Space 内生效；未 USE 时执行语句会报错。
DROP SPACE	`ngql DROP SPACE [IF EXISTS] <space_name>;`	删除图空间及其所有数据和 Schema	`ngql DROP SPACE my_space;`	删除后不可恢复；若 Space 正在被使用，部分版本可能拒绝删除。
SHOW SPACES	`ngql SHOW SPACES;`	列出当前用户可见的所有图空间	`ngql SHOW SPACES;`	返回空间名称列表；不显示内部系统空间。
DESCRIBE SPACE	`ngql DESCRIBE SPACE <space_name>;`	查看图空间的配置信息	`ngql DESCRIBE SPACE my_space;`	显示 partition_num、replica_factor、vid_type 等创建参数。

5.2 Schema 定义（Tag 与 Edge Type）

方法名称	语法	用途	代码示例	注意事项
CREATE TAG	`ngql CREATE TAG [IF NOT EXISTS] <tag_name> (<prop_def>, ...);` prop_def: `<name> <type> [NULL \| NOT NULL]`	创建点标签	`ngql CREATE TAG user(name string, age int, email string);`	属性名在 Tag 内唯一；不支持默认值或约束。
CREATE EDGE	`ngql CREATE EDGE [IF NOT EXISTS] <edge_type> (<prop_def>, ...);`	创建边类型	`ngql CREATE EDGE follow(degree int, create_time timestamp);`	边必须有类型；支持 TTL（需额外选项）。
ALTER TAG	`ngql ALTER TAG <tag_name> ADD \| DROP \| CHANGE <prop_def>;`	修改 Tag 结构	`ngql ALTER TAG user ADD address string;` `ngql ALTER TAG user DROP email;`	不支持重命名 Tag；CHANGE 仅限部分类型兼容转换。
ALTER EDGE	`ngql ALTER EDGE <edge_type> ADD \| DROP \| CHANGE <prop_def>;`	修改 Edge Type 结构	`ngql ALTER EDGE follow ADD remark string;`	同 Tag 修改限制。
DROP TAG	`ngql DROP TAG [IF EXISTS] <tag_name>;`	删除 Tag	`ngql DROP TAG user;`	若存在点使用该 Tag，删除失败。
DROP EDGE	`ngql DROP EDGE [IF EXISTS] <edge_type>;`	删除 Edge Type	`ngql DROP EDGE follow;`	若存在边实例，删除失败。
SHOW TAGS / EDGES	`ngql SHOW TAGS;` `ngql SHOW EDGES;`	列出所有 Tag 或 Edge Type	`ngql SHOW TAGS;`	仅显示当前 Space 下的定义。
DESCRIBE TAG / EDGE	`ngql DESCRIBE TAG <tag_name>;` `ngql DESCRIBE EDGE <edge_type>;`	查看 Schema 详情	`ngql DESCRIBE TAG user;`	显示属性名、类型、是否为空。

5.3 数据插入（INSERT VERTEX/EDGE）

方法名称	语法	用途	代码示例	注意事项
INSERT VERTEX	`ngql INSERT VERTEX [IF NOT EXISTS] <tag_name> (<prop_list>) VALUES <vid>: (<value_list>);`	插入点数据	`ngql INSERT VERTEX user(name, age) VALUES "user100": ("Alice", 30);`	VID 必须符合 Space 的 vid_type；一个点可插入多个 Tag。
INSERT VERTEX 多 Tag	`ngql INSERT VERTEX <tag1> (...), <tag2> (...) VALUES <vid>: (...), <vid>: (...);`	一次插入多个 Tag 的点	`ngql INSERT VERTEX user(name), employee(dept) VALUES "e001": ("Bob", "HR");`	各 Tag 的属性值需按顺序提供。
INSERT EDGE	`ngql INSERT EDGE [IF NOT EXISTS] <edge_type> (<prop_list>) VALUES <src_vid> -> <dst_vid> [@rank]: (<value_list>);`	插入边数据	`ngql INSERT EDGE follow(degree) VALUES "user100" -> "user101": (95);`	rank 为可选 int64，默认 0；用于区分多条同类型边。
批量插入	多个 VALUES 用逗号分隔： `ngql INSERT VERTEX user(name) VALUES "u1":("A"), "u2":("B");`	一次插入多个点或边	`ngql INSERT EDGE follow(degree) VALUES "a"->"b":(80), "b"->"c":(85);`	批量插入效率高于单条多次执行。
ON DUPLICATE KEY UPDATE	`ngql INSERT VERTEX ... ON DUPLICATE KEY UPDATE <prop> = <expr>;`	存在时更新	`ngql INSERT VERTEX user(name) VALUES "u1":("Tom") ON DUPLICATE KEY UPDATE name = "Tom";`	仅更新指定属性；未指定属性保持不变。

5.4 数据查询（FETCH / LOOKUP / GO / MATCH）

方法名称	语法	用途	代码示例	注意事项
FETCH VERTEX	`ngql FETCH PROP ON <tag_name> <vid_list> YIELD <prop_expr>;`	按 VID 获取点属性	`ngql FETCH PROP ON user "user100" YIELD user.name, user.age;`	必须指定 Tag；VID 必须存在，否则返回空。
FETCH EDGE	`ngql FETCH PROP ON <edge_type> <src> -> <dst> [@rank] YIELD <prop_expr>;`	按边获取属性	`ngql FETCH PROP ON follow "user100" -> "user101" YIELD follow.degree;`	rank 可省略，默认取 rank=0 的边。
LOOKUP	`ngql LOOKUP ON <tag/edge> WHERE <prop_condition> YIELD <prop_expr>;`	基于属性索引查找点或边	`ngql LOOKUP ON user WHERE user.age > 25 YIELD user.name;`	必须先为属性创建索引，否则报错。
GO	`ngql GO FROM <vid_list> OVER <edge_type> [REVERSELY] [BIDIRECT] [UPTO N STEPS] YIELD <expr>;`	沿边遍历	`ngql GO FROM "user100" OVER follow YIELD dst(edge);` `ngql GO FROM "A" OVER rel UPTO 3 STEPS YIELD ...;`	支持多跳（STEPS）；REVERSELY 表示反向遍历。
MATCH	`ngql MATCH (v:Tag {prop: value}) -[e:EdgeType]-> (v2) RETURN v, e, v2;`	类 Cypher 的模式匹配查询	`ngql MATCH (p:person)-[f:follow]->(q:person) WHERE p.age > 30 RETURN p.name, f.degree, q.name;`	需启用 MATCH（v3.0+ 默认支持）；性能低于 GO，适合复杂模式。

5.5 数据删除与更新

方法名称	语法	用途	代码示例	注意事项
DELETE VERTEX	`ngql DELETE VERTEX <vid_list> [WITH EDGE];`	删除点（及关联边）	`ngql DELETE VERTEX "user999";` `ngql DELETE VERTEX "user999" WITH EDGE;`	不加 WITH EDGE 仅删点，边变为”悬挂边”；加 WITH EDGE 同时删出边和入边。
DELETE EDGE	`ngql DELETE EDGE <edge_type> <src> -> <dst> [@rank];`	删除指定边	`ngql DELETE EDGE follow "user100" -> "user101";`	必须指定完整的 src/dst/rank 才能删除。
UPDATE VERTEX	`ngql UPDATE VERTEX <vid> SET <tag>.<prop> = <value> [WHEN <condition>] [YIELD <expr>];`	更新点属性	`ngql UPDATE VERTEX "user100" SET user.age = 31 YIELD user.name;`	不能更新 VID；SET 语法类似 SQL。
UPDATE EDGE	`ngql UPDATE EDGE <src> -> <dst> [@rank] OF <edge_type> SET <prop> = <value> [WHEN <condition>] [YIELD <expr>];`	更新边属性	`ngql UPDATE EDGE "user100" -> "user101" OF follow SET degree = 90;`	必须指定 edge_type 和完整边标识。
UPSERT	NebulaGraph 不直接支持 UPSERT 语句，但可通过 `INSERT ... ON DUPLICATE KEY UPDATE` 实现类似效果（见 5.3）	插入或更新	见 5.3 节	仅适用于 INSERT 场景，非通用 UPSERT。

第六章：高级查询与图算法

6.1 路径查询（FIND PATH）

方法名称	语法	用途	代码示例	注意事项
FIND SHORTEST PATH	`ngql FIND SHORTEST PATH FROM <vid_list> TO <vid_list> OVER <edge_type_list> [UPTO <N> STEPS] YIELD path as p;`	查询两点间最短路径（跳数最少）	`ngql FIND SHORTEST PATH FROM "A" TO "D" OVER follow YIELD path as p;`	默认单向；若无路径返回空；不支持属性过滤。
FIND ALL PATH	`ngql FIND ALL PATH FROM <vid_list> TO <vid_list> OVER <edge_type_list> UPTO <N> STEPS YIELD path as p;`	查询两点间所有路径（限定最大跳数）	`ngql FIND ALL PATH FROM "A" TO "C" OVER follow UPTO 3 STEPS YIELD path as p;`	结果可能爆炸式增长，建议限制 STEPS ≤ 5。
双向路径查询	在 edge_type_list 中同时指定正向和反向边类型，模拟无向图路径	模拟无向图路径	`ngql FIND SHORTEST PATH FROM "A" TO "B" OVER follow, follow REVERSELY YIELD path as p;`	实际写法需确认版本支持；部分版本需用 `*` 表示双向。
多起点/多终点	`ngql FIND SHORTEST PATH FROM "A","B" TO "X","Y" OVER rel YIELD path as p;`	批量路径查询	如上	返回所有起点到所有终点的最短路径组合。
路径结果解析	返回的 path 类型包含点序列和边序列，可通过 `nodes(p)`、`relationships(p)` 提取	后处理路径数据	`ngql FIND SHORTEST PATH FROM "A" TO "B" OVER follow YIELD nodes($-.p) AS node_list;`	需配合 YIELD 使用；结果为列表类型。

6.2 子图查询（GET SUBGRAPH）

方法名称	语法	用途	代码示例	注意事项
GET SUBGRAPH	`ngql GET SUBGRAPH [WITH PROP] [<N> STEPS] FROM <vid_list> [IN <edge_type_list>] [OUT <edge_type_list>] [BOTH <edge_type_list>] YIELD vertices as v, edges as e;`	获取以指定点为中心的 N 跳子图	`ngql GET SUBGRAPH 2 STEPS FROM "user100" OUT follow YIELD vertices as v, edges as e;`	默认仅返回 ID；加 WITH PROP 可返回属性。
指定边方向	IN：入边，OUT：出边，BOTH：双向	控制子图遍历方向	`ngql GET SUBGRAPH 1 STEPS FROM "A" BOTH rel YIELD vertices as v;`	若未指定方向，默认为 OUT。
多跳子图	N STEPS 中 N ≥ 1，最大建议 ≤ 5	扩展子图范围	`ngql GET SUBGRAPH 3 STEPS FROM "root" OUT knows YIELD edges as e;`	跳数越大，结果集指数级增长，慎用。
返回带属性子图	使用 WITH PROP	获取完整子图数据用于可视化	`ngql GET SUBGRAPH WITH PROP 2 STEPS FROM "p1" OUT follow YIELD vertices as v, edges as e;`	属性数据会显著增加返回体积和内存消耗。
子图结果结构	vertices：点列表（含 VID 和 Tag 信息） edges：边列表（含 src/dst/type/rank/属性）	供下游处理或导出	可结合 Nebula Explorer 直接渲染	不支持直接对子图做聚合，需在外层处理。

6.3 内置图算法（如最短路径、PageRank 等）

注意：NebulaGraph 核心引擎不直接内置 PageRank、LPA 等算法。这些算法需通过 Nebula Algorithm（Spark 库）或 Nebula Graph Studio/Explorer 插件实现。但部分路径类算法已内置于 nGQL。

方法/工具名称	语法 / 调用方式	用途	代码示例 / 使用方式	注意事项
最短路径（跳数）	见 6.1 节 FIND SHORTEST PATH	基于跳数的最短路径	已在 6.1 节详述	非权重最短路径。
带权重最短路径	核心 nGQL 不支持；需通过应用层实现或使用 Nebula Algorithm 的 ShortestPath 算法	基于边权重的最短路径	使用 Spark 任务调用 Nebula Algorithm 库	需导出数据到 Spark，非实时。
PageRank	通过 Nebula Algorithm（开源 Spark 库）执行	计算节点重要性	配置 YAML 后运行： `bash spark-submit --class com.vesoft.nebula.algorithm.Main nebula-algorithm-3.0.jar -p pagerank.conf`	结果写回 Nebula 或输出到文件；非在线查询。
社区发现（LPA）	Nebula Algorithm 支持 Label Propagation Algorithm	发现密集子图/社区	同上，配置 `algorithm: LPA`	适用于静态图分析。
连通分量（WCC/SCC）	Nebula Algorithm 支持 Weakly/Strongly Connected Components	分析图连通性	配置 `algorithm: WCC`	大图需充足 Spark 资源。
实时中心性（度中心）	使用 nGQL 聚合实现： `ngql GO FROM * OVER follow YIELD src(edge) AS s \| GROUP BY $-.s YIELD $-.s, count(*) AS degree;`	近似度中心性	如上	仅适用于中小图；全图扫描开销大。
路径存在性判断	`ngql GO FROM "A" OVER follow UPTO 5 STEPS YIELD dst(edge) AS d \| WHERE $-.d == "Z" RETURN true;`	判断两点是否连通	可结合 LIMIT 1 优化	非精确算法，但可快速验证。

Nebula Algorithm 简介：

是 Nebula 官方提供的基于 Spark 的图算法库
支持算法：PageRank、LPA、WCC、SCC、ShortestPath、KCore、TriangleCount 等
输入：从 Nebula 导出的点边数据（通过 Nebula Exchange 或 Spark Connector）
输出：结果可写回 Nebula 新 Tag/Edge，或存至 Hive/HDFS

第七章：索引与性能优化

7.1 创建与管理索引

方法名称	语法	用途	代码示例	注意事项
CREATE TAG INDEX	`ngql CREATE [UNIQUE] TAG INDEX <index_name> ON <tag_name>(<prop_list>);`	为点标签属性创建索引	`ngql CREATE TAG INDEX user_age_idx ON user(age);` `ngql CREATE TAG INDEX user_name_age_idx ON user(name, age);`	支持复合索引；UNIQUE 索引要求属性值全局唯一（同一 Tag 内）。
CREATE EDGE INDEX	`ngql CREATE [UNIQUE] EDGE INDEX <index_name> ON <edge_type>(<prop_list>);`	为边类型属性创建索引	`ngql CREATE EDGE INDEX follow_degree_idx ON follow(degree);`	边索引基于 (src, dst, rank, props) 构建，查询时需配合 LOOKUP 使用。
REBUILD INDEX	`ngql REBUILD TAG \| EDGE INDEX <index_name> [OFFLINE];`	构建或重建索引（异步）	`ngql REBUILD TAG INDEX user_age_idx;`	新建索引后必须执行 REBUILD 才能生效；大数据量重建耗时较长。
SHOW TAG/EDGE INDEXES	`ngql SHOW TAG INDEXES;` `ngql SHOW EDGE INDEXES;`	列出当前 Space 下所有索引	`ngql SHOW TAG INDEXES;`	显示索引名、关联 Tag/Edge、属性列表、状态等。
DESCRIBE INDEX	`ngql DESCRIBE TAG \| EDGE INDEX <index_name>;`	查看索引结构	`ngql DESCRIBE TAG INDEX user_age_idx;`	返回索引字段及类型。
DROP INDEX	`ngql DROP TAG \| EDGE INDEX <index_name>;`	删除索引	`ngql DROP TAG INDEX user_age_idx;`	删除后无法用于 LOOKUP 查询；不影响原始数据。
查看索引状态	`ngql SHOW JOB STATUS;` — 查看 REBUILD 进度 `ngql SHOW JOBS;` — 列出所有异步任务	监控索引构建进度	执行 `SHOW JOBS;` 后找到对应 Job ID，再用 `SHOW JOB <id>;` 查看详情	REBUILD 是异步任务，状态为 FINISHED 表示完成。

7.2 查询计划与 EXPLAIN

方法名称	语法	用途	代码示例	注意事项
EXPLAIN	`ngql EXPLAIN <nGQL_statement>;`	显示查询的执行计划（逻辑计划）	`ngql EXPLAIN GO FROM "user100" OVER follow YIELD dst(edge);`	不实际执行查询；用于分析执行步骤。
PROFILE	`ngql PROFILE <nGQL_statement>;`	执行查询并返回带耗时的执行计划	`ngql PROFILE MATCH (v:person)-[e]->(v2) RETURN v.name LIMIT 10;`	实际执行查询；显示每算子的 CPU 时间、行数、内存等。
执行计划字段说明	- operator: 算子类型（如 Start, GetVertices, Traverse, Project） - dependencies: 依赖的上游算子 - rows: 输出行数（PROFILE 中） - execTime: 执行时间（微秒）	理解查询性能瓶颈	在 PROFILE 输出中观察 Traverse 或 GetNeighbors 是否耗时过高	高耗时算子通常对应 Storage 访问或大结果集处理。
优化提示（Hint）	NebulaGraph 暂不支持 SQL-style 的 `/+ index(...) /` 等 Hint 语法	—	—	查询优化主要依赖 Schema 设计和索引。
常见低效模式	- 未使用索引的 LOOKUP - MATCH 全图扫描（无起点过滤） - 多跳 GO 未限制结果集大小	识别反模式	`ngql MATCH (v) RETURN v;` — 全图扫描，极慢	应避免无条件全图遍历。

7.3 性能调优建议

调优方向	操作细节	注意事项
合理设计 VID	- 若点 ID 为字符串，使用 fixed_string(N) 并尽量缩短长度（如 UUID 可转为 base64 缩短） - 若可转为整数，优先使用 int64（性能更高、存储更省）	VID 类型在 CREATE SPACE 时确定，不可更改。
分片（Partition）调优	- 初始 partition_num = Storage 节点数 × 10 - 数据倾斜时通过 BALANCE LEADER 和 BALANCE DATA 重分布	Partition 过少导致热点，过多增加元数据开销。
索引策略	- 仅对高频 WHERE 条件字段建索引 - 避免过度索引（写入性能下降） - 复合索引顺序应匹配查询条件顺序（最左前缀原则）	索引不加速 GO/MATCH 遍历，仅加速 LOOKUP。
查询优化	- 优先使用 GO 而非 MATCH（除非需要复杂模式） - 限制返回结果：LIMIT - 避免 YIELD *，只取必要字段 - 多跳查询加 UPTO N STEPS 限制深度	MATCH 在 v3.x 有优化，但仍慢于 GO。
存储配置优化	- 使用 SSD 磁盘 - 调整 rocksdb_block_cache（默认 512MB，可增至数 GB） - 开启 enable_rocksdb_statistics 监控存储层性能	需修改 nebula-storaged.conf 并重启。
客户端连接复用	- 使用连接池（各语言 SDK 均支持） - 避免频繁创建/销毁连接	单连接非线程安全，多线程需独立连接。
TTL（生存时间）	对时效性数据设置 TTL： `ngql CREATE TAG event(ts timestamp) TTL_DURATION = 86400, TTL_COL = ts;`	自动清理过期数据，减少存储与查询负担。
监控与日志	- 关注 logs/storaged.FATAL / .ERROR - 使用 Prometheus + Grafana 监控（Nebula 提供 exporter） - 关键指标：QPS、延迟、Storage IO、Raft 状态	生产环境必须配置监控告警。

第八章：运维与监控

8.1 日志查看与配置

步骤名称	操作细节	注意事项
日志默认位置	所有服务（metad / graphd / storaged）的日志位于部署目录下的 logs/ 子目录： - nebula-metad.log - nebula-graphd.log - nebula-storaged.log 同时存在 .ERROR, .WARNING, .FATAL 等分级文件	日志轮转由 glog 控制，默认保留最近若干文件。
调整日志级别	修改各服务的配置文件（如 nebula-graphd.conf）中的 minloglevel： - 0 = INFO - 1 = WARNING - 2 = ERROR - 3 = FATAL 例如：`--minloglevel=1`	修改后需重启对应服务生效；生产环境建议设为 1（WARNING），避免 INFO 过多。
设置日志保留策略	在配置文件中调整： - `--logbufsecs=0`（立即刷盘） - `--max_log_size=500`（单个日志文件最大 MB） - `--stop_logging_if_full_disk=true`	避免磁盘被日志占满；建议配合 logrotate 使用。
实时查看关键日志	`bash tail -f logs/nebula-storaged.WARNING` `bash grep "E_RAFT" logs/nebula-storaged.ERROR` # 查看 Raft 异常	关注 E_LEADER_CHANGED, E_RAFT, E_WRITE_FAILURE 等关键词。
启用调试日志	临时调试可启动时加参数： `bash ./bin/nebula-graphd --minloglevel=0 --v=3` 其中 `--v=N` 控制 verbose 级别（N=1～4）	仅用于问题排查，切勿在生产长期开启。
日志格式自定义	Nebula 使用 Google glog，不支持 JSON 或结构化日志原生输出；如需接入 ELK，建议通过 Filebeat 采集并解析文本日志	可通过正则提取 timestamp、level、message 等字段。

8.2 备份与恢复

步骤名称	操作细节	注意事项
使用 CREATE SNAPSHOT	在 console 中执行： `ngql CREATE SNAPSHOT;` 系统将在所有 Storage 节点的 data/storage/snapshot/ 下生成一致性快照	快照是只读的；基于 RocksDB checkpoint，几乎不影响在线服务。
查看快照列表	`ngql SHOW SNAPSHOTS;`	返回快照名（时间戳格式）和状态。
删除快照	`ngql DROP SNAPSHOT <snapshot_name>;`	手动清理旧快照释放磁盘空间。
从快照恢复数据	无法直接在线恢复。需： 1. 停止所有 nebula 服务 2. 备份当前 data/ 目录 3. 将目标快照目录（如 snapshot_20251201_120000）重命名为 data/storage/nebula/ 4. 启动服务	恢复操作会覆盖当前数据；仅适用于灾难恢复；不能跨版本恢复。
使用 BR 工具（推荐）	Nebula 官方提供 Nebula Backup & Restore (BR) 工具（v3.6+）： - 支持全量/增量备份 - 支持 S3/HDFS 等远程存储 - 支持在线恢复到新集群	需单独下载 br 工具；文档见 https://docs.nebula-graph.io/
BR 备份示例	`bash br backup full --meta "192.168.1.10:9559" --storage "s3://mybucket/nebula_backup?access_key=xxx&secret_key=yyy"`	需配置 Meta 服务地址和存储后端。
BR 恢复示例	`bash br restore full --meta "new_meta:9559" --storage "s3://mybucket/nebula_backup/backup_20251201"`	恢复目标必须是空集群；不能覆盖运行中集群。
逻辑导出（nGQL）	使用 LIMIT + FETCH 或 GO 导出为 CSV： `bash nebula-console -e "GO FROM * OVER * YIELD src, edge, dst" --format csv > graph.csv`	仅适用于小规模数据；无 Schema 信息，需手动重建。

8.3 监控指标（通过 Prometheus + Grafana）

步骤名称	操作细节	注意事项
启用 Metrics 输出	在各服务配置文件中启用： `--enable_metric=true` `--metric_interval=10`（秒） Metric 默认通过 HTTP /metrics 端口暴露（graphd:19669, storaged:19670, metad:19667）	需确保防火墙开放对应端口。
配置 Prometheus 抓取	在 prometheus.yml 中添加 job： `yaml scrape_configs: - job_name: 'nebula' static_configs: - targets: ['graphd_host:19669', 'storaged_host:19670', 'metad_host:19667']`	建议按角色分组抓取，便于告警。
导入官方 Grafana Dashboard	从 Nebula 官方 GitHub 下载模板： https://github.com/vesoft-inc/nebula-grafana-dashboard 导入 ID：13737（或最新版）	包含 QPS、延迟、Storage IO、Raft 状态等核心面板。
关键监控指标	- num_queries：查询 QPS - query_latency_us：查询延迟（微秒） - disk_used_bytes：磁盘使用量 - raft_leader_count：Leader 分布 - heartbeat_lost_count：心跳丢失（网络异常）	关注 storaged 的 put_latency 和 get_neighbors_latency。
设置告警规则（Prometheus）	示例：Storage 磁盘使用率 > 85% `yaml groups: - name: nebula-alerts rules: - alert: DiskUsageHigh expr: disk_used_bytes / disk_capacity_bytes > 0.85 for: 5m`	建议配置：Leader 失衡、查询超时、心跳中断、磁盘满等告警。
自定义指标扩展	Nebula 暴露数百个指标（以 nebula_ 为前缀），可通过 PromQL 聚合分析： `promql rate(nebula_graph_query_latency_us_sum[5m]) / rate(nebula_graph_query_latency_us_count[5m])`	用于深度性能分析或容量规划。
监控高可用状态	检查 nebula_metad_heartbeat_lost_count 是否持续增长；检查 nebula_storaged_raft_status 是否为 1（正常）	Raft 状态异常通常表示网络分区或节点宕机。

第九章：客户端与生态集成

9.1 官方客户端（Java / Python / Go）

客户端名称	用途	安装方式	代码示例	注意事项
Java Client	在 Java 应用中连接 NebulaGraph 执行 nGQL	Maven： `xml <dependency> <groupId>com.vesoft</groupId> <artifactId>nebula-java</artifactId> <version>3.8.0</version> </dependency>`	`java NebulaPoolConfig config = new NebulaPoolConfig(); config.setMaxConnSize(10); NebulaPool pool = new NebulaPool(); pool.init(Arrays.asList(new HostAddress("127.0.0.1", 9669)), config); Session session = pool.getSession("root", "nebula", false); ResultSet result = session.execute("USE my_space; GO FROM 'A' OVER follow YIELD dst(edge);");`	需手动管理 Session 生命周期；NebulaPool 线程安全。
Python Client	在 Python 脚本或服务中操作图数据	pip： `bash pip install nebula3-python`	`python from nebula3.gclient.net import ConnectionPool; from nebula3.Config import Config; config = Config(); config.max_connection_pool_size = 10; pool = ConnectionPool(); pool.init([('127.0.0.1', 9669)], config); client = pool.get_session('root', 'nebula'); result = client.execute('GO FROM "A" OVER follow YIELD dst(edge)'); print(result)`	支持 Jupyter Notebook；返回结果可转为 pandas DataFrame。
Go Client	在 Go 微服务中嵌入图查询能力	go get： `bash go get github.com/vesoft-inc/nebula-go/v3`	`go cfg := nebula.GetDefaultConf(); cfg.Address = "127.0.0.1"; cfg.Port = 9669; pool, err := nebula.NewConnectionPool([]nebula.HostAddress{{Host: "127.0.0.1", Port: 9669}}, cfg, nebula.DefaultLogger{}); session, err := pool.GetSession("root", "nebula"); resp, err := session.Execute("GO FROM 'A' OVER follow YIELD dst(edge)");`	需处理 error；支持 context 控制超时。
共同特性	- 支持连接池 - 自动重连（部分版本） - SSL/TLS 加密（需配置） - 支持参数化查询（防止注入）	所有客户端均基于 Thrift 协议与 Graphd 通信	参数化示例（Python）： `python client.execute_parameter("GO FROM ? OVER follow", ["A"])`	参数化语法因语言而异；避免拼接 nGQL 字符串。

9.2 与 Spark / Flink 集成

工具/组件	用途	集成方式	代码/配置示例	注意事项
Nebula Spark Connector	从 Nebula 读取点/边数据到 Spark DataFrame，或将 DataFrame 写入 Nebula	Maven 引入： `xml <dependency> <groupId>com.vesoft</groupId> <artifactId>nebula-spark-connector_2.12</artifactId> <version>3.8.0</version> </dependency>`	`scala val df = spark.read.nebula( metaAddress = "192.168.1.10:9559", space = "my_space", label = "user", returnCols = Seq("name", "age") ).load(); df.show()`	读取基于 LOOKUP 或全扫描；写入需指定 Tag/Edge 和属性映射。
Nebula Exchange	高性能批量导入工具（支持 Spark 分布式写入）	下载 JAR 后通过 Spark Submit 运行	配置 YAML： `yaml tags: - name: user fields: [name, age] vertexes: "hdfs:///users.csv"` 执行： `bash spark-submit --class com.vesoft.nebula.exchange.Exchange nebula-exchange-3.8.0.jar -c config.yaml`	支持 CSV/JSON/Parquet/Hive/Kafka 等源；适用于 TB 级数据初始化。
Nebula Flink Connector	实时流写入 Nebula（如从 Kafka 流处理后写入）	目前官方未提供成熟 Flink Sink；社区方案多基于 Java Client 封装	社区示例： `java public class NebulaSinkFunction implements SinkFunction<MyEvent> { public void invoke(MyEvent e, Context ctx) { // 使用 Java Client 批量插入 } }`	需自行实现幂等、重试、批量提交；不建议高频单条写入。
数据同步方向	- Spark → Nebula：批量写入（Exchange） - Nebula → Spark：分析/算法（Connector） - Flink → Nebula：实时事件写入（自定义）		写入 Nebula 建议批量（每批 1k～10k 条），避免小包频繁请求。

9.3 可视化工具（Nebula Explorer / Studio）

工具名称	用途	部署方式	核心功能	注意事项
Nebula Explorer	企业级图可视化与探索平台（商业版）	Docker 或离线安装包（需 License）	- 拖拽式图探索 - 自定义图样式（颜色/大小/图标） - 路径/子图高亮 - 用户权限管理 - 查询历史与收藏	免费试用 30 天；支持千万级点边渲染（WebGL 加速）。
Nebula Studio	开源轻量级 Web IDE（社区版）	Docker 快速启动： `bash docker run -d --name studio -p 7001:7001 vesoft/nebula-studio:latest`	- nGQL 编辑器（自动补全） - Schema 查看器 - 简易图展示（基于 G6） - 导出查询结果为 CSV	图展示仅适合小规模（<10k 点边）；无用户权限控制。
访问地址	- Explorer: http://<host>:7003 - Studio: http://<host>:7001	首次使用需配置 Graphd 地址和账号		确保前端能访问 Graphd 的 9669 端口（Studio 通过后端代理，Explorer 可直连或代理）。
图探索操作	1. 输入 VID 查询点 2. 点击”展开”加载一跳邻居 3. 框选多点查看路径 4. 保存画布为模板	Explorer 支持”探索模式”自动遍历		大图建议先用 nGQL 限定范围再可视化。
与客户端协同	可在 Studio/Explorer 中调试 nGQL，再将语句集成到 Java/Python 应用中			生产查询逻辑应在应用层实现，可视化工具仅用于探索与验证。