这是本节的多页打印视图。 .
Quick Start
- 1: HugeGraph (OLTP)
- 2: HugeGraph ToolChain
- 3: HugeGraph-AI
- 3.1: HugeGraph-LLM
- 3.2: HugeGraph-ML
- 3.3: HugeGraph-LLM 使用流程
- 3.4: 配置参考
- 3.5: HugeGraph-LLM REST API
- 4: HugeGraph 图计算（OLAP）
- 5: HugeGraph Client
根据需要选择 Server、Toolchain、图计算或 HugeGraph-AI 的快速开始文档。各组件独立发布，安装前请核对对应仓库的运行环境和版本。
1 - HugeGraph (OLTP)
DeepWiki 提供实时更新的项目文档，内容更全面准确，适合快速了解项目最新情况。
GitHub 访问： https://github.com/apache/hugegraph
1.1 - HugeGraph Server 快速开始
1 HugeGraph Server 概述
apache/hugegraph 是 HugeGraph 图数据库的主仓库，包含 hugegraph-server、hugegraph-pd、hugegraph-store 等一级模块。本页介绍其中的 hugegraph-server 模块及其运行服务。
hugegraph-server 模块包含 hugegraph-core、hugegraph-api、hugegraph-dist 和存储适配等子模块。Core 实现属性图模型、事务与 TinkerPop 接口，API 提供 HTTP 服务并将客户端请求交给 Core 处理。图数据由 RocksDB（单机默认）、HStore（分布式）或 HBase 后端保存。
⚠️ 版本说明：本文以 HugeGraph 1.7.0 至
master分支的代码为参考，仅介绍 RocksDB、HStore 和 HBase。其他旧后端的使用与配置请参考 HugeGraph 1.5.x 文档。
名称说明：
HugeGraph表示整个项目或主仓库，hugegraph-server表示仓库中的 Server 模块，HugeGraphServer是服务进程的 Java 类名。下文使用“Server 服务”表示运行中的图数据库服务。
2 依赖
2.1 安装 Java 11 (JDK 11)
HugeGraph 1.7.0 中的 hugegraph-server 模块使用 Java 11 编译，运行和源码构建均需使用 Java 11 或更高版本。
在继续阅读前，请先执行 java -version 命令确认 JDK 版本。
1.7.0 起不再支持 Java 8。
3 部署
有四种方式可以部署 Server 服务：
- 方式 1：使用 Docker 容器 (便于测试)
- 方式 2：下载 tar 包
- 方式 3：源码编译
- 方式 4：使用 tools 工具部署 (Outdated)
不要把 Gremlin、Cypher 等查询接口直接暴露到公网。生产环境应启用认证与授权，限制网络访问并保留审计日志；部署建议见安全指南。
3.1 使用 Docker 容器 (便于测试)
可参考 Docker 部署方式。
可以使用 docker run -itd --name=server -p 8080:8080 -e PASSWORD=xxx hugegraph/hugegraph:1.7.0 快速启动一个使用 RocksDB 后端的 Server 实例。
可选项：
- 可以使用
docker exec -it server bash进入容器执行运维或调试操作。 - 可以使用
docker run -itd --name=server -p 8080:8080 -e PRELOAD="true" hugegraph/hugegraph:1.7.0在启动时预加载一个内置样例图。可通过RESTful API进行验证，具体步骤可参考 5.1.4。 - 可以使用
-e PASSWORD=xxx开启鉴权模式并设置 admin 密码，具体步骤可参考 Config Authentication。
如果使用 Docker Desktop，则可以按如下方式设置相关选项：
注意：Docker Compose 文件使用桥接网络（
hg-net），适用于 Linux 和 Mac（Docker Desktop）。如需运行 3 节点分布式集群，请为 Docker Desktop 分配至少 12 GB 内存（设置 → 资源 → 内存）。Linux 上 Docker 直接使用宿主机内存。
如果希望通过一个配置文件统一管理 HugeGraph 的多个服务实例，则可以使用 docker compose。
docker/ 目录下提供了两个 compose 文件：
- 单节点快速启动（预构建镜像）：
docker/docker-compose.yml - 单节点开发构建（从源码构建）：
docker/docker-compose.dev.yml
如需开启鉴权，可在 compose 文件的环境变量中添加 PASSWORD=xxx，或在 docker run 命令中传入 -e PASSWORD=xxx。
完整的部署指南请参阅 docker/README.md。
注意：
HugeGraph 的 Docker 镜像主要用于便捷地快速启动 HugeGraph，并不是 ASF 官方发布物料包。你可以从 ASF Release Distribution Policy 中了解更多细节。
推荐使用
release tag(如1.7.0/1.x.0) 以获取稳定版。使用latesttag 可以使用开发中的最新功能。
3.2 下载 tar 包
3.3 源码编译
源码编译前请确保本机有安装 wget/curl 命令
下载 HugeGraph 源代码
编译打包生成 tar 包
构建成功时日志中会出现：
执行成功后，在 hugegraph 目录下生成 *hugegraph-*.tar.gz 文件，就是编译生成的 tar 包。
3.4 使用 tools 工具部署 (Outdated)
HugeGraph-Tools 提供一键部署命令，可以下载、解压、配置并启动 Server 服务和 HugeGraph-Hubble。HugeGraph-Toolchain 发布包中已包含这些工具。
注：
${version}为版本号，最新版本号可参考 Download 页面，或直接从 Download 页面点击链接下载
HugeGraph-Tools 的总入口脚本是 bin/hugegraph，用户可以使用 help 子命令查看其用法，这里只介绍一键部署的命令。
{hugegraph-version} 表示要部署的 Server 服务及 HugeGraphStudio 版本，可在 conf/version-mapping.yaml 中查看版本信息。{install-path} 指定安装目录，{download-path-prefix} 可选，用于指定 tar 包下载地址。例如部署 0.6 版本时，可以执行 bin/hugegraph deploy -v 0.6 -p services。
4 配置
如果需要快速启动 HugeGraph 仅用于测试，那么只需要进行少数几个配置项的修改即可（见下一节）。
5 启动
5.1 使用启动脚本启动
启动流程分为“首次启动”和“非首次启动”。首次启动前需要先初始化后端数据库，然后再启动服务。
如果服务曾被手动停止，或因其他原因需要再次启动，由于后端数据库已持久化存在，通常可以直接启动服务。
HugeGraphServer 启动时会连接后端存储并检查其版本信息。如果后端尚未初始化，或者已初始化但版本不匹配（例如存在旧版本数据），HugeGraphServer 会启动失败并给出错误信息。
如果需要外部访问 HugeGraphServer，请修改 rest-server.properties 的 restserver.url 配置项（默认为 http://127.0.0.1:8080），修改成机器名或 IP 地址。
由于各种后端所需的配置（hugegraph.properties）及启动步骤略有不同，下面逐一对各后端的配置及启动做介绍。
注: 如果想要开启 HugeGraph 权限系统，在启动 Server 之前应按照 Server 鉴权配置 进行配置。(尤其是生产环境/外网环境须开启)
5.1.1 分布式存储 (HStore)
分布式存储是 HugeGraph 1.5.0 之后推出的新特性，它基于 HugeGraph-PD 和 HugeGraph-Store 组件实现了分布式的数据存储和计算。
要使用分布式存储引擎，需要先部署 HugeGraph-PD 和 HugeGraph-Store，详见 HugeGraph-PD 快速入门 和 HugeGraph-Store 快速入门。
确保 PD 和 Store 服务均已启动后
- 修改 Server 服务的
hugegraph.properties配置：
- 修改 Server 服务的
rest-server.properties配置：
如果配置多个 Server 节点，需要为每个节点修改 rest-server.properties 配置文件，例如：
节点 1（主节点）：
节点 2（工作节点）：
同时，还需要修改每个节点的 gremlin-server.yaml 中的端口配置：
节点 1：
节点 2：
启动 Server：
使用分布式存储引擎的启动顺序为：
- 启动 HugeGraph-PD
- 启动 HugeGraph-Store
- 启动 Server 服务
HStore 的元数据和存储由 PD、Store 管理，init-store 会跳过该后端，不需要单独执行初始化脚本。
验证服务是否正常启动：
停止服务的顺序应该与启动顺序相反：
- 停止 Server 服务
- 停止 HugeGraph-Store
- 停止 HugeGraph-PD
Docker 分布式集群
通过 Docker-Compose 运行完整的分布式集群（3 PD + 3 Store + 3 Server）：
服务通过 hg-net 桥接网络上的容器主机名进行通信。配置通过环境变量注入：
验证集群：
运行时日志可通过 docker logs <container-name>（如 docker logs hg-pd0）直接查看，无需进入容器。
完整的环境变量参考、端口表和故障排查指南请参阅 docker/README.md。
5.1.2 RocksDB / ToplingDB
以下从本地 properties 文件启动图的示例要求在 conf/rest-server.properties 中设置：
当前源码默认值是 false，上游发布模板尚未写出该选项。
RocksDB 是一个嵌入式的数据库，不需要手动安装部署，要求 GCC 版本 >= 4.3.0（GLIBCXX_3.4.10），如不满足，需要提前升级 GCC
修改 hugegraph.properties
初始化数据库（第一次启动时或在 conf/graphs/ 下手动添加了新配置时需要进行初始化）
启动 server
提示的 url 与 rest-server.properties 中配置的 restserver.url 一致
ToplingDB (Beta): 作为 RocksDB 的高性能替代方案，配置方式请参考: ToplingDB Quick Start
5.1.3 HBase
5.1.4 启动 server 的时候创建示例图
在启动脚本时携带 -p true 参数，表示开启 preload，即创建示例图。
并且使用 RESTful API 请求 HugeGraphServer 得到如下结果：
代表创建示例图成功。
5.2 使用 Docker
在 3.1 使用 Docker 容器 中，我们已经介绍了如何使用 docker 部署 Server 服务。还可以通过切换后端存储或设置参数，在 Server 启动时加载样例图。
5.2.1 启动 server 的时候创建示例图
在 Docker 启动时设置环境变量 PRELOAD=true，即可在启动脚本执行过程中加载样例数据。
使用
docker run使用
docker run -itd --name=server -p 8080:8080 -e PRELOAD=true hugegraph/hugegraph:1.7.0使用
docker-compose创建
docker-compose.yml，具体文件如下，在环境变量中设置 PRELOAD=true。其中，example.groovy是一个预定义的脚本，用于预加载样例数据。如果有需要，可以通过挂载新的example.groovy脚本改变预加载的数据。使用命令
docker-compose up -d启动容器
使用 RESTful API 请求 HugeGraphServer 得到如下结果：
代表创建示例图成功。
6 访问 Server
6.1 服务启动状态校验
jps 查看服务进程
curl 请求 RESTful API
返回结果 200，代表 server 启动正常
6.2 请求 Server
HugeGraphServer 的 RESTful API 包括多种类型的资源，典型的包括 graph、schema、gremlin、traverser 和 task
graph包含vertices、edgesschema包含vertexlabels、propertykeys、edgelabels、indexlabelsgremlin包含各种Gremlin语句，如g.v()，可以同步或者异步执行traverser包含各种高级查询，包括最短路径、交叉点、N 步可达邻居等task包含异步任务的查询和删除
6.2.1 获取 hugegraph 的顶点及相关属性
说明
由于图的点和边很多，对于 list 型的请求，比如获取所有顶点，获取所有边等，Server 会将数据压缩再返回，所以使用 curl 时得到一堆乱码，可以重定向至
gunzip进行解压。推荐使用 Chrome 浏览器 + Restlet 插件发送 HTTP 请求进行测试。当前 HugeGraphServer 的默认配置只能是本机访问，可以修改配置，使其能在其他机器访问。
响应体如下：
详细的 API 请参考 RESTful-API 文档。
另外也可以通过访问 localhost:8080/swagger-ui/index.html 查看 API。
在使用 Swagger UI 调试 HugeGraph 提供的 API 时，如果 HugeGraph Server 开启了鉴权模式，可以在 Swagger 页面输入鉴权信息。
当前 HugeGraph 支持基于 Basic 和 Bearer 两种形式设置鉴权信息。
7 停止 Server
8 使用 IntelliJ IDEA 调试 Server
1.2 - HugeGraph-PD Quick Start
1 HugeGraph-PD 概述
HugeGraph-PD（Placement Driver）是 HugeGraph 分布式版本的元数据管理组件，负责管理图数据的分布和存储节点的协调。它在分布式 HugeGraph 中扮演着核心角色，维护集群状态并协调 HugeGraph-Store 存储节点。
2 依赖
2.1 前置条件
- 操作系统：Linux 或 macOS（Windows 尚未经过完整测试）
- Java 版本：≥ 11
- Maven 版本：≥ 3.5.0
3 部署
有两种方式可以部署 HugeGraph-PD 组件：
- 方式 1：下载 tar 包
- 方式 2：源码编译
3.1 下载 tar 包
从 Apache HugeGraph 官方下载页面下载最新版本的 HugeGraph-PD：
3.2 源码编译
3.3 Docker 部署
HugeGraph-PD Docker 镜像已发布在 Docker Hub，镜像名为 hugegraph/pd。
注: 后续步骤皆假设你本地已拉取
hugegraph主仓库代码 (至少是 docker 目录)
使用 docker-compose 模式部署完整的 3 节点集群（PD + Store + Server）：
通过 docker run 运行单个 PD 节点时，通过环境变量提供配置：
环境变量参考：
| 变量 | 必填 | 默认值 | 描述 |
|---|---|---|---|
HG_PD_GRPC_HOST | 是 | — | 本节点的 gRPC 主机名/IP（Docker 中使用 pd0，裸机使用 192.168.1.10） |
HG_PD_RAFT_ADDRESS | 是 | — | 本节点的 Raft 地址（如 pd0:8610） |
HG_PD_RAFT_PEERS_LIST | 是 | — | 所有 PD 节点的 Raft 地址（如 pd0:8610,pd1:8610,pd2:8610） |
HG_PD_INITIAL_STORE_LIST | 是 | — | 预期的 Store gRPC 地址（如 store0:8500,store1:8500,store2:8500） |
HG_PD_GRPC_PORT | 否 | 8686 | gRPC 服务端口 |
HG_PD_REST_PORT | 否 | 8620 | REST API 端口 |
HG_PD_DATA_PATH | 否 | /hugegraph-pd/pd_data | 元数据存储路径 |
HG_PD_INITIAL_STORE_COUNT | 否 | 1 | 集群可用所需的最小 Store 数量 |
注意：在 Docker 桥接网络中，
HG_PD_GRPC_HOST和HG_PD_RAFT_ADDRESS应使用容器主机名（如pd0）而非 IP 地址。
已弃用的别名：
GRPC_HOST、RAFT_ADDRESS、RAFT_PEERS、PD_INITIAL_STORE_LIST仍可使用，但会输出弃用警告。新部署请使用HG_PD_*名称。
运行时日志可通过 docker logs <container-name>（如 docker logs hg-pd0）直接查看，无需进入容器。
完整的集群部署指南请参阅 docker/README.md。
4 配置
PD 的主要配置文件为 conf/application.yml，以下是关键配置项：
对于多节点部署，需要修改各节点的端口和地址配置，确保各节点之间能够正常通信。
5 启动与停止
5.1 启动 PD
在 PD 安装目录下执行：
启动脚本支持 -d 参数控制守护进程模式：
-d true（默认）：以后台守护进程方式运行，脚本立即返回。-d false：以前台模式运行——脚本通过exec替换为 Java 进程，容器/进程管理器的进程即为 Java 本身。在 Docker 或进程管理器（systemd、supervisord）下运行时请使用此参数，以便在崩溃时自动检测并重启服务。
启动成功后，可以在 logs/hugegraph-pd-stdout.log 中看到类似以下的日志：
5.2 停止 PD
在 PD 安装目录下执行：
6 验证
确认 PD 服务是否正常运行：
如果返回 {"status":"UP"}，则表示 PD 服务已成功启动。
也可以通过 PD API 查看 Store 节点状态：
如果响应中 state 为 Up，说明对应的 Store 节点运行正常。在一个健康的 3 节点部署中，storeId 列表应包含 3 个 ID，且 stateCountMap.Up、numOfService 和 numOfNormalService 都应为 3。
1.3 - HugeGraph-Store Quick Start
1 HugeGraph-Store 概述
HugeGraph-Store 是 HugeGraph 分布式版本的存储节点组件，负责实际存储和管理图数据。它与 HugeGraph-PD 协同工作，共同构成 HugeGraph 的分布式存储引擎，提供高可用性和水平扩展能力。
2 依赖
2.1 前置条件
- 操作系统：Linux 或 macOS（Windows 尚未经过完整测试）
- Java 版本：≥ 11
- Maven 版本：≥ 3.5.0
- 如需进行多节点部署，请先部署 HugeGraph-PD
3 部署
有两种方式可以部署 HugeGraph-Store 组件：
- 方式 1：下载 tar 包
- 方式 2：源码编译
3.1 下载 tar 包
从 Apache HugeGraph 官方下载页面下载最新版本的 HugeGraph-Store：
3.2 源码编译
3.3 Docker 部署
HugeGraph-Store Docker 镜像已发布在 Docker Hub，镜像名是 hugegraph/store。
注: 后续步骤皆假设你本地已拉取
hugegraph主仓库代码 (至少是 docker 目录)
使用 docker-compose 文件部署完整的 3 节点集群（PD + Store + Server）：
通过 docker run 运行单个 Store 节点：
环境变量参考：
| 变量 | 必填 | 默认值 | 描述 |
|---|---|---|---|
HG_STORE_PD_ADDRESS | 是 | — | PD gRPC 地址（如 pd0:8686,pd1:8686,pd2:8686） |
HG_STORE_GRPC_HOST | 是 | — | 本节点的 gRPC 主机名/IP（如 store0） |
HG_STORE_RAFT_ADDRESS | 是 | — | 本节点的 Raft 地址（如 store0:8510） |
HG_STORE_GRPC_PORT | 否 | 8500 | gRPC 服务端口 |
HG_STORE_REST_PORT | 否 | 8520 | REST API 端口 |
HG_STORE_DATA_PATH | 否 | /hugegraph-store/storage | 数据存储路径 |
注意：在 Docker 桥接网络中，
HG_STORE_GRPC_HOST应使用容器主机名（如store0）而非 IP 地址。
已弃用的别名：
PD_ADDRESS、GRPC_HOST、RAFT_ADDRESS仍可使用，但会输出弃用警告。新部署请使用HG_STORE_*名称。
4 配置
Store 的主要配置文件为 conf/application.yml，以下是关键配置项：
对于多节点部署，需要为每个 Store 节点修改以下配置：
- 每个节点的
grpc.port（RPC 端口） - 每个节点的
raft.address（Raft 协议端口） - 每个节点的
server.port（REST 端口） - 每个节点的
app.data-path（数据存储路径）
5 启动与停止
5.1 启动 Store
确保 PD 服务已经启动，然后在 Store 安装目录下执行：
启动脚本支持 -d 参数控制守护进程模式：
-d true（默认）：以后台守护进程方式运行，脚本立即返回。-d false：以前台模式运行——脚本通过exec替换为 Java 进程，容器/进程管理器的进程即为 Java 本身。在 Docker 或进程管理器（systemd、supervisord）下运行时请使用此参数，以便在崩溃时自动检测并重启服务。
启动成功后，可以在 logs/hugegraph-store-server.log 中看到类似以下的日志：
5.2 停止 Store
在 Store 安装目录下执行：
6 多节点部署示例
以下是一个三节点部署的配置示例：
6.1 三节点配置参考
- 3 PD 节点
- raft 端口：8610, 8611, 8612
- rpc 端口：8686, 8687, 8688
- rest 端口：8620, 8621, 8622
- 3 Store 节点
- raft 端口：8510, 8511, 8512
- rpc 端口：8500, 8501, 8502
- rest 端口：8520, 8521, 8522
6.2 Store 节点配置
对于三个 Store 节点，每个节点的主要配置差异如下：
节点 A：
节点 B：
节点 C：
所有节点都应该指向相同的 PD 集群：
6.3 Docker 分布式集群配置
3 节点 Store 集群包含在 docker/docker-compose-3pd-3store-3server.yml 中。每个 Store 节点拥有独立的主机名和环境变量：
Store 节点仅在所有 PD 节点通过健康检查后才会启动，其中 docker-compose 中的 healthcheck 实际访问的是 PD 的 REST 接口 /v1/health（也可以通过 Actuator 暴露的 /actuator/health 进行手动检查），并通过 depends_on: condition: service_healthy 强制执行依赖关系。
运行时日志可通过 docker logs <container-name>（如 docker logs hg-store0）直接查看，无需进入容器。
完整的部署指南请参阅 docker/README.md。
7 验证 Store 服务
确认 Store 服务是否正常运行：
如果返回 {"status":"UP"}，则表示 Store 服务已成功启动。
也可以通过 PD API 查看集群中的 Store 节点状态：
如果 Store 配置成功，上述接口响应中应包含当前节点的状态信息，其中 state 为 Up 表示节点运行正常。
下方示例仅展示 1 个 Store 节点的返回结果。如果 3 个节点都已正确配置并正在运行，则响应中的 storeId 列表应包含 3 个 ID，且 stateCountMap.Up、numOfService 和 numOfNormalService 都应为 3。
2 - HugeGraph ToolChain
测试指南：如需在本地运行工具链测试，请参考 HugeGraph 工具链本地测试指南
HugeGraph Toolchain 包含 Java/Go 客户端、Loader、Hubble、Tools 和 Spark Connector。各模块的功能和使用方法见本节文档。
DeepWiki 提供实时更新的项目文档，内容更全面准确，适合快速了解项目最新情况。
2.1 - HugeGraph-Hubble Quick Start
1 HugeGraph-Hubble 概述
⚠️ 安全提醒：截至 1.7.0 发布版，Hubble 尚未提供 Auth/Login 登录保护；相关功能计划随 1.8.0 发布。请勿将 Hubble 暴露在公网或不受信任的网络中，并使用 IP/端口白名单和 HTTPS 限制访问。
测试指南：如需在本地运行 Hubble 测试，请参考 工具链本地测试指南
HugeGraph-Hubble 是 HugeGraph 的 Web 管理界面，可用于管理图连接和 Schema、导入数据、执行 Gremlin 查询并查看图形化结果。
平台主要包括以下模块：
图管理
图管理用于创建和维护连接，可在多个图之间切换，并执行访问、编辑、删除和查询操作。
元数据建模
元数据建模用于管理 PropertyKey、VertexLabel、EdgeLabel 和 IndexLabel。页面提供列表与图两种视图，也可以在图之间复用元数据。
图分析
图分析页面可以执行 Gremlin 和路径查询，并用图、表格或 JSON 显示结果。页面还保存执行记录和收藏语句，查询结果可以导出为 JSON。
任务管理
任务管理页面用于查看 Gremlin 异步任务、索引创建和重建等后台任务。
数据导入 (BETA)
数据导入页面适合小规模试用。大批量或生产导入请使用 HugeGraph Loader。
数据导入页面按步骤创建任务、上传文件并配置字段映射，可并行运行多个导入任务，也支持断点续传和错误重试。
2 部署
有三种方式可以部署hugegraph-hubble
- 使用 docker (便于测试)
- 下载 toolchain 二进制包
- 源码编译
2.1 使用 Docker (便于测试)
特别注意: docker 模式下，若 hubble 和 server 在同一宿主机，hubble 页面中设置 server 的
hostname不能设置为localhost/127.0.0.1，因这会指向 hubble 容器内部而非宿主机，导致无法连接到 server.若 hubble 和 server 在同一 docker 网络下，推荐直接使用
container_name(如下例的server) 作为主机名。或者也可以使用 宿主机 IP 作为主机名，此时端口号为宿主机给 server 配置的端口
我们可以使用 docker run -itd --name=hubble -p 8088:8088 hugegraph/hubble:1.5.0 快速启动 hubble.
或者使用 docker-compose 启动 hubble，另外如果 hubble 和 server 在同一个 docker 网络下，可以使用 server 的 contain_name 进行访问，而不需要宿主机的 ip
使用docker-compose up -d，docker-compose.yml如下：
注意：
hugegraph-hubble的 docker 镜像是一个便捷发布版本，用于快速测试试用 hubble，并非ASF 官方发布物料包的方式。你可以从 ASF Release Distribution Policy 中得到更多细节。生产环境推荐使用
release tag(如1.5.0) 稳定版。使用latesttag 默认对应 master 最新代码。
2.2 下载 toolchain 二进制包
hubble项目在toolchain项目中，首先下载toolchain的 tar 包
运行hubble
启动完成后访问 http://<host>:8088。停止服务时执行 bin/stop-hubble.sh。
2.3 源码编译
Hubble 的构建由 hugegraph-hubble/hubble-dist/pom.xml 中的 frontend-maven-plugin 安装 Node.js 18.20.8 和 Yarn 1.22.21，无需预先安装这两个工具。
下载 toolchain 源码包
编译hubble, 它依赖 loader 和 client, 编译时需提前构建这些依赖 (后续可跳)
启动hubble
3 平台使用流程
平台的模块使用流程如下：
4 平台使用说明
4.1 图管理
4.1.1 图创建
图管理模块下，点击【创建图】，通过填写图 ID、图名称、主机名、端口号、用户名、密码的信息，实现多图的连接。
创建图填写内容如下：
注意：如果使用 docker 启动
hubble，且server和hubble位于同一宿主机，不能直接使用localhost/127.0.0.1作为主机名。如果hubble和server在同一 docker 网络下，则可以直接使用 container_name 作为主机名，端口则为 8080。或者也可以使用宿主机 ip 作为主机名，此时端口为宿主机为 server 配置的端口
4.1.2 图访问
实现图空间的信息访问，进入后，可进行图的多维查询分析、元数据管理、数据导入、算法分析等操作。
4.1.3 图管理
- 用户通过对图的概览、搜索以及单图的信息编辑与删除，实现图的统一管理。
- 搜索范围：可对图名称和 ID 进行搜索。
4.2 元数据建模（列表 + 图模式）
4.2.1 模块入口
左侧导航处：
4.2.2 属性类型
4.2.2.1 创建
- 填写或选择属性名称、数据类型、基数，完成属性的创建。
- 创建的属性可作为顶点类型和边类型的属性。
列表模式：
图模式：
4.2.2.2 复用
- 平台提供【复用】功能，可直接复用其他图的元数据。
- 选择需要复用的图 ID，继续选择需要复用的属性，之后平台会进行是否冲突的校验，通过后，可实现元数据的复用。
选择复用项：
校验复用项：
4.2.2.3 管理
- 在属性列表中可进行单条删除或批量删除操作。
4.2.3 顶点类型
4.2.3.1 创建
- 填写或选择顶点类型名称、ID 策略、关联属性、主键属性，顶点样式、查询结果中顶点下方展示的内容，以及索引的信息：包括是否创建类型索引，及属性索引的具体内容，完成顶点类型的创建。
列表模式：
图模式：
4.2.3.2 复用
- 顶点类型的复用，会将此类型关联的属性和属性索引一并复用。
- 复用功能使用方法类似属性的复用，见 3.2.2.2。
4.2.3.3 管理
可进行编辑操作，顶点样式、关联类型、顶点展示内容、属性索引可编辑，其余不可编辑。
可进行单条删除或批量删除操作。
4.2.4 边类型
4.2.4.1 创建
- 填写或选择边类型名称、起点类型、终点类型、关联属性、是否允许多次连接、边样式、查询结果中边下方展示的内容，以及索引的信息：包括是否创建类型索引，及属性索引的具体内容，完成边类型的创建。
列表模式：
图模式：
4.2.4.2 复用
- 边类型的复用，会将此类型的起点类型、终点类型、关联的属性和属性索引一并复用。
- 复用功能使用方法类似属性的复用，见 3.2.2.2。
4.2.4.3 管理
- 可进行编辑操作，边样式、关联属性、边展示内容、属性索引可编辑，其余不可编辑，同顶点类型。
- 可进行单条删除或批量删除操作。
4.2.5 索引类型
展示顶点类型和边类型的顶点索引和边索引。
4.3 数据导入
注意：目前推荐使用 hugegraph-loader 进行正式数据导入，hubble 内置的导入用来做测试和简单上手
数据导入的使用流程如下：
4.3.1 模块入口
左侧导航处：
4.3.2 创建任务
- 填写任务名称和备注（非必填），可以创建导入任务。
- 可创建多个导入任务，并行导入。
4.3.3 上传文件
- 上传需要构图的文件，目前支持的格式为 CSV，后续会不断更新。
- 可同时上传多个文件。
4.3.4 设置数据映射
对上传的文件分别设置数据映射，包括文件设置和类型设置
文件设置：勾选或填写是否包含表头、分隔符、编码格式等文件本身的设置内容，均设置默认值，无需手动填写
类型设置：
顶点映射和边映射：
【顶点类型】 ：选择顶点类型，并为其 ID 映射上传文件中列数据；
【边类型】：选择边类型，为其起点类型和终点类型的 ID 列映射上传文件的列数据；
映射设置：为选定的顶点类型的属性映射上传文件中的列数据，此处，若属性名称与文件的表头名称一致，可自动匹配映射属性，无需手动填选
完成设置后，显示设置列表，方可进行下一步操作，支持映射的新增、编辑、删除操作
设置映射的填写内容：
映射列表：
4.3.5 导入数据
导入前需要填写导入设置参数，填写完成后，可开始向图库中导入数据
- 导入设置
- 导入设置参数项如下图所示，均设置默认值，无需手动填写
- 导入详情
- 点击开始导入，开始文件的导入任务
- 导入详情中提供每个上传文件设置的映射类型、导入速度、导入的进度、耗时以及当前任务的具体状态，并可对每个任务进行暂停、继续、停止等操作
- 若导入失败，可查看具体原因
4.4 数据分析
4.4.1 模块入口
左侧导航处：
4.4.2 多图切换
通过左侧切换入口，灵活切换多图的操作空间
4.4.3 图分析与处理
HugeGraph 支持 Apache TinkerPop3 的图遍历查询语言 Gremlin，Gremlin 是一种通用的图数据库查询语言，通过输入 Gremlin 语句，点击执行，即可执行图数据的查询分析操作，并可实现顶点/边的创建及删除、顶点/边的属性修改等。
Gremlin 查询后，下方为图结果展示区域，提供 3 种图结果展示方式，分别为：【图模式】、【表格模式】、【Json 模式】。
⚠️ SEC 提醒：Hubble 允许在网页端直接输入并执行 Gremlin 原生查询语句，这赋予了使用者较高的操作权限。请避免将 Hubble 服务暴露在公网环境，建议在使用时确保图数据库服务端已开启 鉴权体系 (Auth) 并配合 IP 白名单进行严格的权限控制，防止未授权访问或恶意代码执行风险。
支持缩放、居中、全屏、导出等操作。
【图模式】
【表格模式】
【Json 模式】
4.4.4 数据详情
点击顶点/边实体，可查看顶点/边的数据详情，包括：顶点/边类型，顶点 ID，属性及对应值，拓展图的信息展示维度，提高易用性。
4.4.5 图结果的多维路径查询
除了全局的查询外，可针对查询结果中的顶点进行深度定制化查询以及隐藏操作，实现图结果的定制化挖掘。
右击顶点，出现顶点的菜单入口，可进行展示、查询、隐藏等操作。
- 展开：点击后，展示与选中点关联的顶点。
- 查询：通过选择与选中点关联的边类型及边方向，在此条件下，再选择其属性及相应筛选规则，可实现定制化的路径展示。
- 隐藏：点击后，隐藏选中点及与之关联的边。
双击顶点，也可展示与选中点关联的顶点。
4.4.6 新增顶点/边
4.4.6.1 新增顶点
在图区可通过两个入口，动态新增顶点，如下：
- 点击图区面板，出现添加顶点入口
- 点击右上角的操作栏中的首个图标
通过选择或填写顶点类型、ID 值、属性信息，完成顶点的增加。
入口如下：
添加顶点内容如下：
4.4.6.2 新增边
右击图结果中的顶点，可增加该点的出边或者入边。
4.4.7 执行记录与收藏的查询
- 图区下方记载每次查询记录，包括：查询时间、执行类型、内容、状态、耗时、以及【收藏】和【加载】操作，实现图执行的全方位记录，有迹可循，并可对执行内容快速加载复用
- 提供语句的收藏功能，可对常用语句进行收藏操作，方便高频语句快速调用
4.5 任务管理
4.5.1 模块入口
左侧导航处：
4.5.2 任务管理
- 提供异步任务的统一的管理与结果查看，异步任务包括 4 类，分别为：
- gremlin：Gremlin 任务务
- algorithm：OLAP 算法任务务
- remove_schema：删除元数据
- rebuild_index：重建索引
- 列表显示当前图的异步任务信息，包括：任务 ID，任务名称，任务类型，创建时间，耗时，状态，操作，实现对异步任务的管理。
- 支持对任务类型和状态进行筛选
- 支持搜索任务 ID 和任务名称
- 可对异步任务进行删除或批量删除操作
4.5.3 Gremlin 异步任务
1.创建任务
- 数据分析模块，目前支持两种 Gremlin 操作，Gremlin 查询和 Gremlin 任务；若用户切换到 Gremlin 任务，点击执行后，在异步任务中心会建立一条异步任务； 2.任务提交
- 任务提交成功后，图区部分返回提交结果和任务 ID 3.任务详情
- 提供【查看】入口，可跳转到任务详情查看当前任务具体执行情况跳转到任务中心后，直接显示当前执行的任务行
点击查看入口，跳转到任务管理列表，如下：
4.查看结果
- 结果通过 json 形式展示
4.5.4 OLAP 算法任务
Hubble 上暂未提供可视化的 OLAP 算法执行，可调用 RESTful API 进行 OLAP 类算法任务，在任务管理中通过 ID 找到相应任务，查看进度与结果等。
4.5.5 删除元数据、重建索引
1.创建任务
- 在元数据建模模块中，删除元数据时，可建立删除元数据的异步任务
- 在编辑已有的顶点/边类型操作中，新增索引时，可建立创建索引的异步任务
2.任务详情
- 确认/保存后，可跳转到任务中心查看当前任务的详情
5 配置说明
HugeGraph-Hubble 可以通过 conf/hugegraph-hubble.properties 文件进行配置。
5.1 服务器配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
hubble.host | 0.0.0.0 | Hubble 服务绑定的地址 |
hubble.port | 8088 | Hubble 服务监听的端口 |
5.2 Server 与 PD
| 配置项 | 默认值 | 说明 |
|---|---|---|
pd.enabled | false | 是否通过 PD 发现服务；单机 Server 保持为 false |
server.direct_url | http://127.0.0.1:8080 | pd.enabled=false 时连接的 Server 地址 |
pd.peers | 127.0.0.1:8686 | PD 节点地址 |
pd.server | 127.0.0.1:8620 | PD 服务地址 |
route.type | NODE_PORT | 服务路由方式，可选 NODE_PORT、DDS 或 BOTH |
5.3 Gremlin 查询限制
这些设置控制查询结果限制，防止内存问题：
| 配置项 | 默认值 | 说明 |
|---|---|---|
gremlin.suffix_limit | 250 | 查询后缀最大长度 |
gremlin.vertex_degree_limit | 100 | 显示的最大顶点度数 |
gremlin.edges_total_limit | 500 | 返回的最大边数 |
gremlin.batch_query_ids | 100 | ID 批量查询大小 |
2.2 - HugeGraph-Loader Quick Start
1 HugeGraph-Loader 概述
HugeGraph-Loader 是 HugeGraph 的数据导入组件，能够将多种数据源的数据转化为图的顶点和边并批量导入到图数据库中。
目前支持的数据源包括：
- 本地磁盘文件或目录，支持 TEXT、CSV 和 JSON 格式的文件，支持压缩文件
- HDFS 文件或目录，支持压缩文件
- 主流关系型数据库，如 MySQL、PostgreSQL、Oracle、SQL Server
本地磁盘文件和 HDFS 文件支持断点续传。
后面会具体说明。
注意：使用 HugeGraph-Loader 需要依赖 HugeGraph Server 服务，下载和启动 Server 请参考 HugeGraph-Server Quick Start
测试指南：如需在本地运行 Loader 测试，请参考 工具链本地测试指南
2 获取 HugeGraph-Loader
可以通过以下三种方式获取 HugeGraph-Loader：
- 使用 Docker 镜像 (便于测试)
- 下载已编译的压缩包
- 克隆源码编译安装
2.1 使用 Docker 镜像 (便于测试)
我们可以使用 docker run -itd --name loader hugegraph/loader:1.5.0 部署 loader 服务。对于需要加载的数据，则可以通过挂载 -v /path/to/data/file:/loader/file 或者 docker cp 的方式将文件复制到 loader 容器内部。
或者使用 docker-compose 启动 loader, 启动命令为 docker-compose up -d, 样例的 docker-compose.yml 如下所示：
具体的数据导入流程可以参考 4.5 使用 docker 导入
注意：
hugegraph-loader 的 docker 镜像是一个便捷版本，用于快速启动 loader，并不是官方发布物料包方式。你可以从 ASF Release Distribution Policy 中得到更多细节。
推荐使用
release tag(如1.5.0) 以获取稳定版。使用latesttag 可以使用开发中的最新功能。
2.2 下载已编译的压缩包
下载最新版本的 HugeGraph-Toolchain Release 包，里面包含了 loader + tool + hubble 全套工具，如果你已经下载，可跳过重复步骤
2.3 克隆源码编译安装
克隆最新版本的 HugeGraph-Loader 源码包：
由于 Oracle ojdbc license 的限制，需要手动安装 ojdbc 到本地 maven 仓库。 访问 Oracle jdbc 下载 页面。选择 Oracle Database 12c Release 2 (12.2.0.1) drivers，如下图所示。
打开链接后，选择“ojdbc8.jar”
把 ojdbc8 安装到本地 maven 仓库，进入ojdbc8.jar所在目录，执行以下命令。
编译生成 tar 包：
3 使用流程
使用 HugeGraph-Loader 的基本流程分为以下几步：
- 编写图模型
- 准备数据文件
- 编写输入源映射文件
- 执行命令导入
3.1 编写图模型
这一步是建模的过程，用户需要对自己已有的数据和想要创建的图模型有一个清晰的构想，然后编写 schema 建立图模型。
比如想创建一个拥有两类顶点及两类边的图，顶点是"人"和"软件"，边是"人认识人"和"人创造软件"，并且这些顶点和边都带有一些属性，比如顶点"人"有：“姓名”、“年龄"等属性， “软件"有：“名字”、“售卖价格"等属性；边"认识"有：“日期"属性等。
示例图模型
在设计好了图模型之后，我们可以用groovy编写出schema的定义，并保存至文件中，这里命名为schema.groovy。
关于 schema 的详细说明请参考 hugegraph-client 中对应部分。
3.2 准备数据
目前 HugeGraph-Loader 支持的数据源包括：
- 本地磁盘文件或目录
- HDFS 文件或目录
- 部分关系型数据库
- Kafka topic
3.2.1 数据源结构
3.2.1.1 本地磁盘文件或目录
用户可以指定本地磁盘文件作为数据源，如果数据分散在多个文件中，也支持以某个目录作为数据源，但暂时不支持以多个目录作为数据源。
比如：我的数据分散在多个文件中，part-0、part-1 … part-n，要想执行导入，必须保证它们是放在一个目录下的。然后在 loader 的映射文件中，将path指定为该目录即可。
支持的文件格式包括：
- TEXT
- CSV
- JSON
TEXT 是自定义分隔符的文本文件，第一行通常是标题，记录了每一列的名称，也允许没有标题行（在映射文件中指定）。其余的每行代表一条记录，会被转化为一个顶点/边；行的每一列对应一个字段，会被转化为顶点/边的 id、label 或属性；
示例如下：
CSV 是分隔符为逗号,的 TEXT 文件，当列值本身包含逗号时，该列值需要用双引号包起来，如：
JSON 文件要求每一行都是一个 JSON 串，且每行的格式需保持一致。
3.2.1.2 HDFS 文件或目录
用户也可以指定 HDFS 文件或目录作为数据源，上面关于本地磁盘文件或目录的要求全部适用于这里。除此之外，鉴于 HDFS 上通常存储的都是压缩文件，loader 也提供了对压缩文件的支持，并且本地磁盘文件或目录同样支持压缩文件。
目前支持的压缩文件类型包括：GZIP、BZ2、XZ、LZMA、SNAPPY_RAW、SNAPPY_FRAMED、Z、DEFLATE、LZ4_BLOCK、LZ4_FRAMED、ORC 和 PARQUET。
3.2.1.3 主流关系型数据库
loader 还支持以部分关系型数据库作为数据源，目前支持 MySQL、PostgreSQL、Oracle 和 SQL Server。
但目前对表结构要求较为严格，如果导入过程中需要做关联查询，这样的表结构是不允许的。关联查询的意思是：在读到表的某行后，发现某列的值不能直接使用（比如外键），需要再去做一次查询才能确定该列的真实值。
举个例子：假设有三张表，person、software 和 created
如果在建模（schema）时指定 person 或 software 的 id 策略是 PRIMARY_KEY，选择以 name 作为 primary keys（注意：这是 hugegraph 中 vertexlabel 的概念），在导入边数据时，由于需要拼接出源顶点和目标顶点的 id，必须拿着 p_id/s_id 去 person/software 表中查到对应的 name，这种需要做额外查询的表结构的情况，loader 暂时是不支持的。这时可以采用以下两种方式替代：
- 仍然指定 person 和 software 的 id 策略为 PRIMARY_KEY，但是以 person 表和 software 表的 id 列作为顶点的主键属性，这样导入边时直接使用 p_id 和 s_id 和顶点的 label 拼接就能生成 id 了；
- 指定 person 和 software 的 id 策略为 CUSTOMIZE，然后直接以 person 表和 software 表的 id 列作为顶点 id，这样导入边时直接使用 p_id 和 s_id 即可；
关键点就是要让边能直接使用 p_id 和 s_id，不要再去查一次。
3.2.2 准备顶点和边数据
3.2.2.1 顶点数据
顶点数据文件由一行一行的数据组成，一般每一行作为一个顶点，每一列会作为顶点属性。下面以 CSV 格式作为示例进行说明。
- person 顶点数据（数据本身不包含 header）
- software 顶点数据（数据本身包含 header）
3.2.2.2 边数据
边数据文件由一行一行的数据组成，一般每一行作为一条边，其中有部分列会作为源顶点和目标顶点的 id，其他列作为边属性。下面以 JSON 格式作为示例进行说明。
- knows 边数据
- created 边数据
3.3 编写数据源映射文件
3.3.1 映射文件概述
输入源的映射文件用于描述如何将输入源数据与图的顶点类型/边类型建立映射关系，以JSON格式组织，由多个映射块组成，其中每一个映射块都负责将一个输入源映射为顶点和边。
具体而言，每个映射块包含一个输入源和多个顶点映射与边映射块，输入源块对应上面介绍的本地磁盘文件或目录、HDFS 文件或目录和关系型数据库，负责描述数据源的基本信息，比如数据在哪，是什么格式的，分隔符是什么等。顶点映射/边映射与该输入源绑定，可以选择输入源的哪些列，哪些列作为 id、哪些列作为属性，以及每一列映射成什么属性，列的值映射成属性的什么值等等。
以最通俗的话讲，每一个映射块描述了：要导入的文件在哪，文件的每一行要作为哪一类顶点/边，文件的哪些列是需要导入的，以及这些列对应顶点/边的什么属性等。
注意：0.11.0 版本以前的映射文件与 0.11.0 以后的格式变化较大，为表述方便，下面称 0.11.0 以前的映射文件（格式）为 1.0 版本，0.11.0 以后的为 2.0 版本。并且若无特殊说明，“映射文件”表示的是 2.0 版本的。
这里直接给出两个版本的映射文件（描述了上面图模型和数据文件）
映射文件 1.0 版本是以顶点和边为中心，设置输入源；而 2.0 版本是以输入源为中心，设置顶点和边映射。有些输入源（比如一个文件）既能生成顶点，也能生成边，如果用 1.0 版的格式写，就需要在 vertex 和 edge 映射块中各写一次 input 块，这两次的 input 块是完全一样的；而 2.0 版本只需要写一次 input。所以 2.0 版相比于 1.0 版，能省掉一些 input 的重复书写。
在 hugegraph-loader-{version} 的 bin 目录下，有一个脚本工具 mapping-convert.sh 能直接将 1.0 版本的映射文件转换为 2.0 版本的，使用方式如下：
会在 struct.json 的同级目录下生成一个 struct-v2.json。
3.3.2 输入源
输入源目前分为五类：FILE、HDFS、JDBC、KAFKA 和 GRAPH，由type节点区分，我们称为本地文件输入源、HDFS 输入源、JDBC 输入源和 KAFKA 输入源，图数据源，下面分别介绍。
3.3.2.1 本地文件输入源
- id: 输入源的 id，该字段用于支持一些内部功能，非必填（未填时会自动生成），强烈建议写上，对于调试大有裨益；
- skip: 是否跳过该输入源，由于 JSON 文件无法添加注释，如果某次导入时不想导入某个输入源，但又不想删除该输入源的配置，则可以设置为 true 将其跳过，默认为 false，非必填；
- input: 输入源映射块，复合结构
- type: 输入源类型，必须填 file 或 FILE；
- path: 本地文件或目录的路径，绝对路径或相对于映射文件的相对路径，建议使用绝对路径，必填；
- file_filter: 从
path中筛选复合条件的文件，复合结构，目前只支持配置扩展名，用子节点extensions表示，默认为”*"，表示保留所有文件； - format: 本地文件的格式，可选值为 CSV、TEXT 及 JSON，必须大写，必填；
- header: 文件各列的列名，如不指定则会以数据文件第一行作为 header；当文件本身有标题且又指定了 header，文件的第一行会被当作普通的数据行；JSON 文件不需要指定 header，选填；
- delimiter: 文件行的列分隔符，默认以逗号
","作为分隔符，JSON文件不需要指定，选填； - charset: 文件的编码字符集，默认
UTF-8，选填； - date_format: 自定义的日期格式，默认值为 yyyy-MM-dd HH:mm:ss，选填；如果日期是以时间戳的形式呈现的，此项须写为
timestamp（固定写法）； - time_zone: 设置日期数据是处于哪个时区的，默认值为
GMT+8，选填； - skipped_line: 想跳过的行，复合结构，目前只能配置要跳过的行的正则表达式，用子节点
regex描述，默认不跳过任何行，选填； - compression: 文件的压缩格式，可选值为 NONE、GZIP、BZ2、XZ、LZMA、SNAPPY_RAW、SNAPPY_FRAMED、Z、DEFLATE、LZ4_BLOCK、LZ4_FRAMED、ORC 和 PARQUET，默认为 NONE，表示非压缩文件，选填；
- list_format: 当文件 (非 JSON ) 的某列是集合结构时（对应图中的 PropertyKey 的 Cardinality 为 Set 或 List），可以用此项设置该列的起始符、分隔符、结束符，复合结构：
- start_symbol: 集合结构列的起始符 (默认值是
[, JSON 格式目前不支持指定) - elem_delimiter: 集合结构列的分隔符 (默认值是
|, JSON 格式目前只支持原生,分隔) - end_symbol: 集合结构列的结束符 (默认值是
], JSON 格式目前不支持指定)
- start_symbol: 集合结构列的起始符 (默认值是
3.3.2.2 HDFS 输入源
上述本地文件输入源的节点及含义这里基本都适用，下面仅列出 HDFS 输入源不一样的和特有的节点。
- type: 输入源类型，必须填 hdfs 或 HDFS，必填；
- path: HDFS 文件或目录的路径，必须是 HDFS 的绝对路径，必填；
- core_site_path: HDFS 集群的 core-site.xml 文件路径，重点要指明 NameNode 的地址（
fs.default.name），以及文件系统的实现（fs.hdfs.impl）；
3.3.2.3 JDBC 输入源
前面说到过支持多种关系型数据库，但由于它们的映射结构非常相似，故统称为 JDBC 输入源，然后用vendor节点区分不同的数据库。
- type: 输入源类型，必须填 jdbc 或 JDBC，必填；
- vendor: 数据库类型，可选项为 [MySQL、PostgreSQL、Oracle、SQLServer]，不区分大小写，必填；
- driver: jdbc 使用的 driver 类型，必填；
- url: jdbc 要连接的数据库的 url，必填；
- database: 要连接的数据库名，必填；
- schema: 要连接的 schema 名，不同的数据库要求不一样，下面详细说明；
- table: 要连接的表名，
custom_sql和table参数必须填其中一个； - custom_sql: 自定义 SQL 语句，
custom_sql和table参数必须填其中一个； - username: 连接数据库的用户名，必填；
- password: 连接数据库的密码，必填；
- batch_size: 按页获取表数据时的一页的大小，默认为 500，选填；
MYSQL
| 节点 | 固定值或常见值 |
|---|---|
| vendor | MYSQL |
| driver | com.mysql.cj.jdbc.Driver |
| url | jdbc:mysql://127.0.0.1:3306 |
schema: 可空，若填写必须与 database 的值一样
POSTGRESQL
| 节点 | 固定值或常见值 |
|---|---|
| vendor | POSTGRESQL |
| driver | org.postgresql.Driver |
| url | jdbc:postgresql://127.0.0.1:5432 |
schema: 可空，默认值为“public”
ORACLE
| 节点 | 固定值或常见值 |
|---|---|
| vendor | ORACLE |
| driver | oracle.jdbc.driver.OracleDriver |
| url | jdbc:oracle:thin:@127.0.0.1:1521 |
schema: 可空，默认值与用户名相同
SQLSERVER
| 节点 | 固定值或常见值 |
|---|---|
| vendor | SQLSERVER |
| driver | com.microsoft.sqlserver.jdbc.SQLServerDriver |
| url | jdbc:sqlserver://127.0.0.1:1433 |
schema: 必填
3.3.2.4 Kafka 输入源
- type：输入源类型，必须填
kafka或KAFKA，必填； - bootstrap_server：设置 kafka bootstrap server 列表；
- topic：订阅的 topic；
- group：Kafka 消费者组；
- from_beginning：设置是否从头开始读取；
- format：本地文件的格式，可选值为 CSV、TEXT 及 JSON，必须大写，必填；
- header：文件各列的列名，如不指定则会以数据文件第一行作为 header；当文件本身有标题且又指定了 header，文件的第一行会被当作普通的数据行；JSON 文件不需要指定 header，选填；
- delimiter：文件行的列分隔符，默认以逗号”,“作为分隔符，JSON 文件不需要指定，选填；
- charset：文件的编码字符集，默认 UTF-8，选填；
- date_format：自定义的日期格式，默认值为 yyyy-MM-dd HH:mm:ss，选填；如果日期是以时间戳的形式呈现的，此项须写为 timestamp（固定写法）；
- extra_date_formats：自定义的其他日期格式列表，默认为空，选填；列表中每一项都是一个 date_format 指定日期格式的备用日期格式；
- time_zone：置日期数据是处于哪个时区的，默认值为 GMT+8，选填；
- skipped_line：想跳过的行，复合结构，目前只能配置要跳过的行的正则表达式，用子节点 regex 描述，默认不跳过任何行，选填；
- early_stop：某次从 Kafka broker 拉取的记录为空，停止任务，默认为 false，仅用于调试，选填；
3.3.2.5 GRAPH 输入源
- type：输入源类型，必须填
graph或GRAPH，必填； - graphspace：源图空间名称，默认为
DEFAULT； - graph： 源图名称，必填；
- username：HugeGraph 用户名；
- password：HugeGraph 密码；
- selected_vertices：要同步的顶点筛选规则；
- ignored_vertices：要忽略的顶点筛选规则；
- selected_edges：要同步的边筛选规则；
- ignored_edges：要忽略的边筛选规则；
- pd-peers：HugeGraph-PD 节点地址；
- meta-endpoints：源集群 Meta服务端点；
- cluster：源集群名称；
- batch_size：批量读取源图数据的批次大小，默认为500；
3.3.3 顶点和边映射
顶点和边映射的节点（JSON 文件中的一个 key）有很多相同的部分，下面先介绍相同部分，再分别介绍顶点映射和边映射的特有节点。
相同部分的节点
- label: 待导入的顶点/边数据所属的
label，必填； - field_mapping: 将输入源列的列名映射为顶点/边的属性名，选填；
- value_mapping: 将输入源的数据值映射为顶点/边的属性值，选填；
- selected: 选择某些列插入，其他未选中的不插入，不能与
ignored同时存在，选填； - ignored: 忽略某些列，使其不参与插入，不能与
selected同时存在，选填； - null_values: 可以指定一些字符串代表空值，比如"NULL”，如果该列对应的顶点/边属性又是一个可空属性，那在构造顶点/边时不会设置该属性的值，选填；
- update_strategies: 如果数据需要按特定方式批量更新时可以对每个属性指定具体的更新策略 (具体见下)，选填；
- unfold: 是否将列展开，展开的每一列都会与其他列一起组成一行，相当于是展开成了多行；比如文件的某一列（id 列）的值是
[1,2,3]，其他列的值是18,Beijing，当设置了 unfold 之后，这一行就会变成 3 行，分别是：1,18,Beijing，2,18,Beijing和3,18,Beijing。需要注意的是此项只会展开被选作为 id 的列。默认 false，选填；
更新策略支持 8 种 : (需要全大写)
- 数值累加 :
SUM - 两个数字/日期取更大的:
BIGGER - 两个数字/日期取更小:
SMALLER - Set属性取并集：
UNION - Set属性取交集：
INTERSECTION - List属性追加元素：
APPEND - List/Set属性删除元素：
ELIMINATE - 覆盖已有属性：
OVERRIDE
注意： 如果新导入的属性值为空，会采用已有的旧数据而不会采用空值，效果可以参考如下示例
注意 : 采用了批量更新的策略后, 磁盘读请求数会大幅上升, 导入速度相比纯写覆盖会慢数倍 (此时HDD磁盘IOPS会成为瓶颈, 建议采用SSD以保证速度)
顶点映射的特有节点
- id: 指定某一列作为顶点的 id 列，当顶点 id 策略为
CUSTOMIZE时，必填；当 id 策略为PRIMARY_KEY时，必须为空；
边映射的特有节点
- source: 选择输入源某几列作为源顶点的 id 列，当源顶点的 id 策略为
CUSTOMIZE时，必须指定某一列作为顶点的 id 列；当源顶点的 id 策略为PRIMARY_KEY时，必须指定一列或多列用于拼接生成顶点的 id，也就是说，不管是哪种 id 策略，此项必填； - target: 指定某几列作为目标顶点的 id 列，与 source 类似，不再赘述；
- unfold_source: 是否展开文件的 source 列，效果与顶点映射中的类似，不再赘述；
- unfold_target: 是否展开文件的 target 列，效果与顶点映射中的类似，不再赘述；
3.4 执行命令导入
准备好图模型、数据文件以及输入源映射关系文件后，接下来就可以将数据文件导入到图数据库中。
导入过程由用户提交的命令控制，用户可以通过不同的参数控制执行的具体流程。
3.4.1 参数说明
| 参数 | 默认值 | 是否必传 | 描述信息 |
|---|---|---|---|
-f 或 --file | Y | 配置脚本的路径 | |
-g 或 --graph | hugegraph | 图名称 | |
--graphspace | DEFAULT | 图空间 | |
-s 或 --schema | schema 文件路径；已有 Schema 时可以不传 | ||
-h 或 --host 或 -i | localhost | HugeGraphServer 的地址 | |
-p 或 --port | 8080 | HugeGraphServer 的端口号 | |
--username | null | 当 HugeGraphServer 开启了权限认证时，当前图的 username | |
--password | null | 当 HugeGraphServer 开启了权限认证时，当前图的 password | |
--create-graph | false | 是否在图不存在时自动创建 | |
--token | null | 当 HugeGraphServer 开启了权限认证时，当前图的 token | |
--protocol | http | 向服务端发请求的协议，可选 http 或 https | |
--pd-peers | PD 服务节点地址 | ||
--pd-token | 访问 PD 服务的 token | ||
--meta-endpoints | 元信息存储服务地址 | ||
--direct | false | 是否直连 HugeGraph-Store | |
--route-type | NODE_PORT | 路由选择方式（可选值：NODE_PORT / DDS / BOTH） | |
--cluster | hg | 集群名 | |
--trust-store-file | 请求协议为 https 时，客户端的证书文件路径 | ||
--trust-store-password | 请求协议为 https 时，客户端证书密码 | ||
--clear-all-data | false | 导入数据前是否清除服务端的原有数据 | |
--clear-timeout | 240 | 导入数据前清除服务端的原有数据的超时时间 | |
--incremental-mode | false | 是否使用断点续导模式，仅输入源为 FILE 和 HDFS 支持该模式，启用该模式能从上一次导入停止的地方开始导入 | |
--failure-mode | false | 失败模式为 true 时，会导入之前失败了的数据，一般来说失败数据文件需要在人工更正编辑好后，再次进行导入 | |
--batch-insert-threads | CPUs | 批量插入线程池大小 (CPUs 是当前 OS 可用逻辑核个数) | |
--single-insert-threads | 8 | 单条插入线程池的大小 | |
--max-conn | 4 * CPUs | HugeClient 与 HugeGraphServer 的最大 HTTP 连接数，调整线程的时候建议同时调整此项 | |
--max-conn-per-route | 2 * CPUs | HugeClient 与 HugeGraphServer 每个路由的最大 HTTP 连接数，调整线程的时候建议同时调整此项 | |
--batch-size | 500 | 导入数据时每个批次包含的数据条数 | |
--max-parse-errors | 1 | 最多允许多少行数据解析错误，达到该值则程序退出 | |
--max-insert-errors | 500 | 最多允许多少行数据插入错误，达到该值则程序退出 | |
--timeout | 60 | 插入结果返回的超时时间（秒） | |
--shutdown-timeout | 10 | 多线程停止的等待时间（秒） | |
--retry-times | 3 | 发生超时时的最大重试次数 | |
--retry-interval | 10 | 重试之前的间隔时间（秒） | |
--check-vertex | false | 插入边时是否检查边所连接的顶点是否存在 | |
--print-progress | true | 是否在控制台实时打印导入条数 | |
--dry-run | false | 打开该模式，只解析不导入，通常用于测试 | |
--help 或 -help | false | 打印帮助信息 | |
--parser-threads 或 --parallel-count | max(2,CPUs/2) | 并行读取管线数；--parallel-count 已弃用 | |
--start-file | 0 | 用于部分（分片）导入的起始文件索引 | |
--end-file | -1 | 用于部分导入的截止文件索引 | |
--scatter-sources | false | 分散（并行）读取多个数据源以优化 I/O 性能 | |
--cdc-flush-interval | 30000 | Flink CDC 的数据刷新间隔 | |
--cdc-sink-parallelism | 1 | Flink CDC 写入端（Sink）的并行度 | |
--max-read-errors | 1 | 程序退出前允许的最大读取错误行数 | |
--max-read-lines | -1L | 最大读取行数限制；一旦达到此行数，导入任务将停止 | |
--test-mode | false | 是否开启测试模式 | |
--use-prefilter | false | 是否预先过滤顶点 | |
--short-id | [] | 将自定义 ID 映射为更短的 ID | |
--vertex-edge-limit | -1L | 单个顶点的最大边数限制 | |
--sink-type | true | 是否输出至不同的存储 | |
--vertex-partitions | 64 | HBase 顶点表的预分区数量 | |
--edge-partitions | 64 | HBase 边表的预分区数量 | |
--vertex-table-name | HBase 顶点表名称 | ||
--edge-table-name | HBase 边表名称 | ||
--hbase-zk-quorum | HBase Zookeeper 集群地址 | ||
--hbase-zk-port | HBase Zookeeper 端口号 | ||
--hbase-zk-parent | HBase Zookeeper 根路径 | ||
--restore | false | 将图模式设置为恢复模式 (RESTORING) | |
--backend | hstore | 自动创建图（如果不存在）时的后端存储类型 | |
--serializer | binary | 自动创建图（如果不存在）时的序列化器类型 | |
--scheduler-type | distributed | 自动创建图（如果不存在）时的任务调度器类型 | |
--batch-failure-fallback | true | 批量插入失败时是否回退至单条插入模式 |
3.4.2 断点续导模式
通常情况下，Loader 任务都需要较长时间执行，如果因为某些原因导致导入中断进程退出，而下次希望能从中断的点继续导，这就是使用断点续导的场景。
用户设置命令行参数 –incremental-mode 为 true 即打开了断点续导模式。断点续导的关键在于进度文件，导入进程退出的时候，会把退出时刻的导入进度
记录到进度文件中，进度文件位于 ${struct} 目录下，文件名形如 load-progress ${date} ，${struct} 为映射文件的前缀，${date} 为导入开始
的时刻。比如：在 2019-10-10 12:30:30 开始的一次导入任务，使用的映射文件为 struct-example.json，则进度文件的路径为与 struct-example.json
同级的 struct-example/load-progress 2019-10-10 12:30:30。
注意：进度文件的生成与 –incremental-mode 是否打开无关，每次导入结束都会生成一个进度文件。
如果数据文件格式都是合法的，是用户自己停止（CTRL + C 或 kill，kill -9 不支持）的导入任务，也就是说没有错误记录的情况下，下一次导入只需要设置 为断点续导即可。
但如果是因为太多数据不合法或者网络异常，达到了 –max-parse-errors 或 –max-insert-errors 的限制，Loader 会把这些插入失败的原始行记录到 失败文件中，用户对失败文件中的数据行修改后，设置 –reload-failure 为 true 即可把这些"失败文件"也当作输入源进行导入（不影响正常的文件的导入）， 当然如果修改后的数据行仍然有问题，则会被再次记录到失败文件中（不用担心会有重复行）。
每个顶点映射或边映射有数据插入失败时都会产生自己的失败文件，失败文件又分为解析失败文件（后缀 .parse-error）和插入失败文件（后缀 .insert-error），
它们被保存在 ${struct}/current 目录下。比如映射文件中有一个顶点映射 person 和边映射 knows，它们各有一些错误行，当 Loader 退出后，在
${struct}/current 目录下会看到如下文件：
- person-b4cd32ab.parse-error: 顶点映射 person 解析错误的数据
- person-b4cd32ab.insert-error: 顶点映射 person 插入错误的数据
- knows-eb6b2bac.parse-error: 边映射 knows 解析错误的数据
- knows-eb6b2bac.insert-error: 边映射 knows 插入错误的数据
.parse-error 和 .insert-error 并不总是一起存在的，只有存在解析出错的行才会有 .parse-error 文件，只有存在插入出错的行才会有 .insert-error 文件。
3.4.3 logs 目录文件说明
程序执行过程中各日志及错误数据会写入 hugegraph-loader.log 文件中。
3.4.4 执行命令
运行 bin/hugegraph-loader 并传入参数
4 完整示例
下面给出的是 hugegraph-loader 包中 example 目录下的例子。(GitHub 地址)
4.1 准备数据
顶点文件：example/file/vertex_person.csv
顶点文件：example/file/vertex_software.txt
边文件：example/file/edge_knows.json
边文件：example/file/edge_created.json
4.2 编写 schema
4.3 编写输入源映射文件example/file/struct.json
4.4 执行命令导入
导入结束后，会出现类似如下统计信息：
4.5 使用 docker 导入
4.5.1 使用 docker exec 直接导入数据
4.5.1.1 数据准备
如果仅仅尝试使用 loader, 我们可以使用内置的 example 数据集进行导入，无需自己额外准备数据
如果使用自定义的数据，则在使用 loader 导入数据之前，我们需要将数据复制到容器内部。
首先我们可以根据 4.1-4.3 的步骤准备数据，将准备好的数据通过 docker cp 复制到 loader 容器内部。
假设我们已经按照上述的步骤准备好了对应的数据集，存放在 hugegraph-dataset 文件夹下，文件结构如下：
将文件复制到容器内部
4.5.1.2 数据导入
以内置的 example 数据集为例，我们可以使用以下的命令对数据进行导入。
如果需要导入自己准备的数据集，则只需要修改 -f 配置脚本的路径 以及 -s schema 文件路径即可。
其他的参数可以参照 3.4.1 参数说明
如果导入用户自定义的数据集，按照刚才的例子，则使用：
如果
loader和server位于同一 docker 网络，则可以指定-h {server_container_name}, 否则需要指定server的宿主机的 ip (在我们的例子中，server_container_name为server).
然后我们可以观察到结果：
也可以使用 curl 或者 hubble观察导入结果，此处以 curl 为例：
如果想检查边的导入结果，可以使用 curl "http://localhost:8080/graphs/hugegraph/graph/edges" | gunzip
4.5.2 进入 docker 容器进行导入
除了直接使用 docker exec 导入数据，我们也可以进入容器进行数据导入，基本流程与 4.5.1 相同
使用 docker exec -it loader bash进入容器内部，并执行命令
执行的结果如 4.5.1 所示
4.6 使用 spark-loader 导入
Spark 版本：Spark 3+，其他版本未测试。 当前源码使用 Spark 3.2.2 和 Scala 2.12；其他组合需自行验证。
spark-loader 的参数分为两部分，注意：因二者参数名缩写存在重合部分，请使用参数全称。两种参数之间无需保证先后顺序。
- hugegraph 参数（参考：hugegraph-loader 参数说明 ）
- Spark 任务提交参数（参考：Submitting Applications）
示例：
2.3 - HugeGraph-Tools Quick Start
1 HugeGraph-Tools概述
HugeGraph-Tools 是 HugeGraph 的自动化部署、管理和备份/还原组件。
测试指南：如需在本地运行 Tools 测试，请参考 工具链本地测试指南
2 获取 HugeGraph-Tools
HugeGraph-Tools 包含在 Toolchain 发布包中，可以下载发布包，也可以从源码编译。
- 下载二进制tar包
- 下载源码编译安装
2.1 下载二进制tar包
下载最新版本的 HugeGraph-Toolchain 包, 然后进入 tools 子目录
2.2 下载源码编译安装
源码编译前请确保安装了wget命令
下载最新版本的 HugeGraph-Toolchain 源码包, 然后根目录编译或者单独编译 tool 子模块：
编译生成 tar 包:
生成 tar 包 hugegraph-tools-${version}.tar.gz
3 使用
3.1 功能概览
解压后，进入 hugegraph-tools 目录，可以使用bin/hugegraph或者bin/hugegraph help来查看 usage 信息。主要分为：
- 图管理类，graph-mode-set、graph-mode-get、graph-list、graph-get、graph-clear、graph-create、graph-clone 和 graph-drop
- 异步任务管理类，task-list、task-get、task-delete、task-cancel 和 task-clear
- Gremlin类，gremlin-execute 和 gremlin-schedule
- 备份/恢复类，backup、restore、migrate、schedule-backup 和 dump
- 认证数据备份/恢复类，auth-backup 和 auth-restore
- 安装部署类，deploy、clear、start-all 和 stop-all
3.2 [options]-全局变量
options是 HugeGraph-Tools 的全局变量，可以在 hugegraph-tools/bin/hugegraph 中配置,包括：
- –graph，HugeGraph-Tools 操作的图的名字，默认值是 hugegraph
- –url，HugeGraph-Server 的服务地址，默认是 http://127.0.0.1:8080
- –user，当 HugeGraph-Server 开启认证时，传递用户名
- –password，当 HugeGraph-Server 开启认证时，传递用户的密码
- –timeout，连接 HugeGraph-Server 时的超时时间，默认是 30s
- –protocol，连接协议，可选 http 或 https，默认是 http
- –trust-store-file，证书文件的路径，当 –url 使用 https 时，HugeGraph-Client 使用的 truststore 文件，默认为空，代表使用 hugegraph-tools 内置的 truststore 文件 conf/hugegraph.truststore
- –trust-store-password，证书文件的密码，当 –url 使用 https 时，HugeGraph-Client 使用的 truststore 的密码，默认为空，代表使用 hugegraph-tools 内置的 truststore 文件的密码
上述全局变量，也可以通过环境变量来设置。一种方式是在命令行使用 export 设置临时环境变量，在该命令行关闭之前均有效
| 全局变量 | 环境变量 | 示例 |
|---|---|---|
| –url | HUGEGRAPH_URL | export HUGEGRAPH_URL=http://127.0.0.1:8080 |
| –graph | HUGEGRAPH_GRAPH | export HUGEGRAPH_GRAPH=hugegraph |
| –user | HUGEGRAPH_USERNAME | export HUGEGRAPH_USERNAME=admin |
| –password | HUGEGRAPH_PASSWORD | export HUGEGRAPH_PASSWORD=test |
| –timeout | HUGEGRAPH_TIMEOUT | export HUGEGRAPH_TIMEOUT=30 |
| –trust-store-file | HUGEGRAPH_TRUST_STORE_FILE | export HUGEGRAPH_TRUST_STORE_FILE=/tmp/trust-store |
| –trust-store-password | HUGEGRAPH_TRUST_STORE_PASSWORD | export HUGEGRAPH_TRUST_STORE_PASSWORD=xxxx |
另一种方式是在 bin/hugegraph 脚本中设置环境变量：
3.3 图管理类，graph-mode-set、graph-mode-get、graph-list、graph-get、graph-clear、graph-create、graph-clone和graph-drop
- graph-mode-set，设置图的 restore mode
- –graph-mode 或者 -m，必填项，指定将要设置的模式，合法值包括 [NONE, RESTORING, MERGING, LOADING]
- graph-mode-get，获取图的 restore mode
- graph-list，列出某个 HugeGraph-Server 中全部的图
- graph-get，获取某个图及其存储后端类型
- graph-clear，清除某个图的全部 schema 和 data
- –confirm-message 或者 -c，必填项，删除确认信息，需要手动输入，二次确认防止误删，“I’m sure to delete all data”，包括双引号
- graph-create，使用配置文件创建新图
- –name 或者 -n，选填项，新图的名称，默认为 hugegraph
- –file 或者 -f，必填项，图配置文件的路径
- graph-clone，克隆已存在的图
- –name 或者 -n，选填项，新克隆图的名称，默认为 hugegraph
- –clone-graph-name，选填项，要克隆的源图名称，默认为 hugegraph
- graph-drop，删除图（不同于 graph-clear，这会完全删除图）
- –confirm-message 或者 -c，必填项，确认消息 “I’m sure to drop the graph”，包括双引号
当需要把备份的图原样恢复到一个新的图中的时候，需要先将图模式设置为 RESTORING 模式；当需要将备份的图合并到已存在的图中时，需要先将图模式设置为 MERGING 模式。
3.4 异步任务管理类，task-list、task-get和task-delete
- task-list，列出某个图中的异步任务，可以根据任务的状态过滤
- –status，选填项，指定要查看的任务的状态，即按状态过滤任务
- –limit，选填项，指定要获取的任务的数目，默认为 -1，意思为获取全部符合条件的任务
- task-get，获取某个异步任务的详细信息
- –task-id，必填项，指定异步任务的 ID
- task-delete，删除某个异步任务的信息
- –task-id，必填项，指定异步任务的 ID
- task-cancel，取消某个异步任务的执行
- –task-id，要取消的异步任务的 ID
- task-clear，清理完成的异步任务
- –force，选填项，设置时，表示清理全部异步任务，未执行完成的先取消，然后清除所有异步任务。默认只清理已完成的异步任务
3.5 Gremlin类，gremlin-execute和gremlin-schedule
- gremlin-execute，发送 Gremlin 语句到 HugeGraph-Server 来执行查询或修改操作，同步执行，结束后返回结果
- –file 或者 -f，指定要执行的脚本文件，UTF-8编码，与 –script 互斥
- –script 或者 -s，指定要执行的脚本字符串，与 –file 互斥
- –aliases 或者 -a，Gremlin 别名设置，格式为：key1=value1,key2=value2,…
- –bindings 或者 -b，Gremlin 绑定设置，格式为：key1=value1,key2=value2,…
- –language 或者 -l，Gremlin 脚本的语言，默认为 gremlin-groovy
–file 和 –script 二者互斥，必须设置其中之一
- gremlin-schedule，发送 Gremlin 语句到 HugeGraph-Server 来执行查询或修改操作，异步执行，任务提交后立刻返回异步任务id
- –file 或者 -f，指定要执行的脚本文件，UTF-8编码，与 –script 互斥
- –script 或者 -s，指定要执行的脚本字符串，与 –file 互斥
- –bindings 或者 -b，Gremlin 绑定设置，格式为：key1=value1,key2=value2,…
- –language 或者 -l，Gremlin 脚本的语言，默认为 gremlin-groovy
–file 和 –script 二者互斥，必须设置其中之一
3.6 备份/恢复类
- backup，将某张图中的 schema 或者 data 备份到 HugeGraph 系统之外，以 JSON 形式存在本地磁盘或者 HDFS
- –format，备份的格式，可选值包括 [json, text]，默认为 json
- –all-properties，是否备份顶点/边全部的属性，仅在 –format 为 text 是有效，默认 false
- –label，要备份的顶点/边的类型，仅在 –format 为 text 是有效，只有备份顶点或者边的时候有效
- –properties，要备份的顶点/边的属性，逗号分隔，仅在 –format 为 text 是有效，只有备份顶点或者边的时候有效
- –compress，备份时是否压缩数据，默认为 true
- –directory 或者 -d，存储 schema 或者 data 的目录，本地目录时，默认为’./{graphName}’，HDFS 时，默认为 ‘{fs.default.name}/{graphName}’
- –huge-types 或者 -t，要备份的数据类型，逗号分隔，可选值为 ‘all’ 或者 一个或多个 [vertex,edge,vertex_label,edge_label,property_key,index_label] 的组合，‘all’ 代表全部6种类型，即顶点、边和所有schema
- –log 或者 -l，指定日志目录，默认为当前目录
- –retry，指定失败重试次数，默认为 3
- –thread-num 或者 -T，使用的线程数，默认为 Math.min(10, Math.max(4, CPUs / 2))
- –split-size 或者 -s，指定在备份时对顶点或者边分块的大小，默认为 1048576
- -D，用 -Dkey=value 的模式指定动态参数，用来备份数据到 HDFS 时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000
- restore，将 JSON 格式存储的 schema 或者 data 恢复到一个新图中（RESTORING 模式）或者合并到已存在的图中（MERGING 模式）
- –directory 或者 -d，存储 schema 或者 data 的目录，本地目录时，默认为’./{graphName}’，HDFS 时，默认为 ‘{fs.default.name}/{graphName}’
- –clean，是否在恢复图完成后删除 –directory 指定的目录，默认为 false
- –huge-types 或者 -t，要恢复的数据类型，逗号分隔，可选值为 ‘all’ 或者 一个或多个 [vertex,edge,vertex_label,edge_label,property_key,index_label] 的组合，‘all’ 代表全部6种类型，即顶点、边和所有schema
- –log 或者 -l，指定日志目录，默认为当前目录
- –retry，指定失败重试次数，默认为 3
- –thread-num 或者 -T，使用的线程数，默认为 Math.min(10, Math.max(4, CPUs / 2))
- -D，用 -Dkey=value 的模式指定动态参数，用来从 HDFS 恢复图时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000
只有当 –format 为 json 执行 backup 时，才可以使用 restore 命令恢复
- migrate，将当前连接的图迁移至另一个 HugeGraphServer 中
- –target-graph，目标图的名字，默认为 hugegraph
- –target-url，目标图所在的 HugeGraphServer，默认为 http://127.0.0.1:8081
- –target-user，访问目标图的用户名
- –target-password，访问目标图的密码
- –target-timeout，访问目标图的超时时间
- –target-trust-store-file，访问目标图使用的 truststore 文件
- –target-trust-store-password，访问目标图使用的 truststore 的密码
- –directory 或者 -d，迁移过程中，存储源图的 schema 或者 data 的目录，本地目录时，默认为’./{graphName}’，HDFS 时，默认为 ‘{fs.default.name}/{graphName}’
- –huge-types 或者 -t，要迁移的数据类型，逗号分隔，可选值为 ‘all’ 或者 一个或多个 [vertex,edge,vertex_label,edge_label,property_key,index_label] 的组合，‘all’ 代表全部6种类型，即顶点、边和所有schema
- –log 或者 -l，指定日志目录，默认为当前目录
- –retry，指定失败重试次数，默认为 3
- –split-size 或者 -s，指定迁移过程中对源图进行备份时顶点或者边分块的大小，默认为 1048576
- -D，用 -Dkey=value 的模式指定动态参数，用来在迁移图过程中需要备份数据到 HDFS 时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000
- –graph-mode 或者 -m，将源图恢复到目标图时将目标图设置的模式，合法值包括 [RESTORING, MERGING]
- –keep-local-data，是否保留在迁移图的过程中产生的源图的备份，默认为 false，即默认迁移图结束后不保留产生的源图备份
- schedule-backup，周期性对图执行备份操作，并保留一定数目的最新备份（目前仅支持本地文件系统）
- –directory 或者 -d，必填项，指定备份数据的目录
- –backup-num，选填项，指定保存的最新的备份的数目，默认为 3
- –interval，选填项，指定进行备份的周期，格式同 Linux crontab 格式
- dump，把整张图的顶点和边全部导出，默认以
vertex vertex-edge1 vertex-edge2...的 JSON 格式存储。 用户也可以自定义存储格式。在hugegraph-tools/src/main/java/org/apache/hugegraph/formatter下实现一个继承自Formatter的类，例如CustomFormatter，使用时指定该类为 formatter：bin/hugegraph dump -f CustomFormatter- –formatter 或者 -f，指定使用的 formatter，默认为 JsonFormatter
- –directory 或者 -d，存储 schema 或者 data 的目录，默认为当前目录
- –log 或者 -l，指定日志目录，默认为当前目录
- –retry，指定失败重试次数，默认为 3
- –split-size 或者 -s，指定在备份时对顶点或者边分块的大小，默认为 1048576
- -D，用 -Dkey=value 的模式指定动态参数，用来备份数据到 HDFS 时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000
3.7 认证数据备份/恢复类
- auth-backup，备份认证数据到指定目录
- –types 或者 -t，要备份的认证数据类型，逗号分隔，可选值为 ‘all’ 或者一个或多个 [user, group, target, belong, access] 的组合，‘all’ 代表全部5种类型
- –directory 或者 -d，备份数据存储目录，默认为当前目录
- –log 或者 -l，指定日志目录，默认为当前目录
- –retry，指定失败重试次数，默认为 3
- –thread-num 或者 -T，使用的线程数，默认为 Math.min(10, Math.max(4, CPUs / 2))
- -D，用 -Dkey=value 的模式指定动态参数，用来备份数据到 HDFS 时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000
- auth-restore，从指定目录恢复认证数据
- –types 或者 -t，要恢复的认证数据类型，逗号分隔，可选值为 ‘all’ 或者一个或多个 [user, group, target, belong, access] 的组合，‘all’ 代表全部5种类型
- –directory 或者 -d，备份数据存储目录，默认为当前目录
- –log 或者 -l，指定日志目录，默认为当前目录
- –retry，指定失败重试次数，默认为 3
- –thread-num 或者 -T，使用的线程数，默认为 Math.min(10, Math.max(4, CPUs / 2))
- –strategy，冲突处理策略，可选值为 [stop, ignore]，默认为 stop。stop 表示遇到冲突时停止恢复，ignore 表示忽略冲突继续恢复
- –init-password，恢复用户时设置的初始密码，恢复用户数据时必填
- -D，用 -Dkey=value 的模式指定动态参数，用来从 HDFS 恢复数据时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000
3.8 安装部署类
- deploy，一键下载、安装和启动 HugeGraph-Server 和 HugeGraph-Studio
- -v，必填项，指定要安装的 HugeGraph-Server 和 HugeGraph-Studio 版本
- -p，必填项，指定安装的 HugeGraph-Server 和 HugeGraph-Studio 目录
- -u，选填项，指定下载 HugeGraph-Server 和 HugeGraph-Studio 压缩包的链接
- clear，清理 HugeGraph-Server 和 HugeGraph-Studio 目录和tar包
- -p，必填项，指定要清理的 HugeGraph-Server 和 HugeGraph-Studio 的目录
- start-all，一键启动 HugeGraph-Server 和 HugeGraph-Studio，并启动监控，服务死掉时自动拉起服务
- -v，必填项，指定已安装的 HugeGraph-Server 和 HugeGraph-Studio 版本
- -p，必填项，指定安装了 HugeGraph-Server 和 HugeGraph-Studio 的目录
- stop-all，一键关闭 HugeGraph-Server 和 HugeGraph-Studio
deploy命令中有可选参数 -u，提供时会使用指定的下载地址替代默认下载地址下载 tar 包，并且将地址写入
~/hugegraph-download-url-prefix文件中；之后如果不指定地址时，会优先从~/hugegraph-download-url-prefix指定的地址下载 tar 包；如果 -u 和~/hugegraph-download-url-prefix都没有时，会从默认下载地址进行下载
3.9 具体命令参数
各子命令的具体参数如下：
3.10 具体命令示例
1. gremlin语句
2. 查看task情况
3. 图模式查看和设置
4. 清理图
5. 图备份
6. 周期性的备份
7. 图恢复
8. 图迁移
2.4 - HugeGraph-Spark-Connector Quick Start
1 HugeGraph-Spark-Connector 概述
HugeGraph-Spark-Connector 使用 Spark DataFrame API 将批量数据写入 HugeGraph。当前实现提供顶点和边的写入器。
2 环境要求
- Java 8+
- Maven 3.6+
- Spark 3.x
- Scala 2.12
3 编译
3.1 不执行测试的编译
以下命令均在仓库根目录执行。
3.2 执行默认测试的编译
4 使用方法
先在 pom.xml 中添加依赖，并将 ${revision} 换成实际使用的发布版本：
4.1 Schema 定义示例
假设我们有一个图，其 schema 定义如下：
4.2 写入顶点数据（Scala）
4.3 写入边数据（Scala）
5 配置参数
5.1 客户端配置
客户端配置用于配置 hugegraph-client。
| 参数 | 默认值 | 说明 |
|---|---|---|
host | localhost | HugeGraphServer 的地址 |
port | 8080 | HugeGraphServer 的端口 |
graph | hugegraph | 图名称 |
protocol | http | 向服务器发送请求的协议，可选 http 或 https |
username | null | 当 HugeGraphServer 开启权限认证时，当前图的用户名 |
token | null | 当 HugeGraphServer 开启权限认证时，当前图的 token |
timeout | 60 | 插入结果返回的超时时间（秒） |
max-conn | CPUS * 4 | HugeClient 与 HugeGraphServer 之间的最大 HTTP 连接数 |
max-conn-per-route | CPUS * 2 | HugeClient 与 HugeGraphServer 之间每个路由的最大 HTTP 连接数 |
trust-store-file | null | 当请求协议为 https 时，客户端的证书文件路径 |
trust-store-token | null | 当请求协议为 https 时，客户端的证书密码 |
5.2 图数据配置
图数据配置用于说明 DataFrame 如何映射到顶点或边。
| 参数 | 默认值 | 说明 |
|---|---|---|
data-type | 图数据类型，必须是 vertex 或 edge | |
label | 要导入的顶点/边数据所属的标签 | |
id | 指定某一列作为顶点的 id 列。当顶点 id 策略为 CUSTOMIZE 时，必填；当 id 策略为 PRIMARY_KEY 时，必须为空 | |
source-name | 选择输入源的某些列作为源顶点的 id 列。当源顶点的 id 策略为 CUSTOMIZE 时，必须指定某一列作为顶点的 id 列；当源顶点的 id 策略为 PRIMARY_KEY 时，必须指定一列或多列用于拼接生成顶点的 id，即无论使用哪种 id 策略，此项都是必填的 | |
target-name | 指定某些列作为目标顶点的 id 列，与 source-name 类似 | |
selected-fields | 选择某些列进行插入，其他未选择的列不插入，不能与 ignored-fields 同时存在 | |
ignored-fields | 忽略某些列使其不参与插入，不能与 selected-fields 同时存在 | |
batch-size | 500 | 导入数据时每批数据的条目数 |
5.3 通用配置
通用配置包含一些常用的配置项。
| 参数 | 默认值 | 说明 |
|---|---|---|
delimiter | , | source-name、target-name、selected-fields 或 ignored-fields 的分隔符 |
6 许可证
与 HugeGraph 一样，hugegraph-spark-connector 也采用 Apache 2.0 许可证。
3 - HugeGraph-AI
hugegraph-ai 提供 HugeGraph 的 Python 客户端、图机器学习工具，以及面向知识图谱构建和 GraphRAG 的 LLM 工具。
Apache License 2.0 · Ask DeepWiki
模块
- hugegraph-llm：知识图谱构建、GraphRAG 和自然语言图查询。
- hugegraph-ml：从 HugeGraph 读取图数据并运行图学习模型。
- hugegraph-python-client：管理 Schema、图数据和 Gremlin 查询的 Python SDK。
- vermeer-python-client：调用 Vermeer 图计算服务的 Python SDK。
仓库使用 uv workspace 管理 LLM 和 Python 客户端。HugeGraph-ML 是路径依赖模块，不在 workspace members 中。
环境要求
- HugeGraph-LLM：Python 3.10 或 3.11
- HugeGraph-ML、Python 客户端：Python 3.10 或更高版本
uv0.7 或更高版本- HugeGraph Server 1.5 或更高版本
Docker Compose 部署
仓库提供同时启动 HugeGraph Server 和 RAG 服务的 Compose 文件：
默认地址：
- HugeGraph Server：
http://localhost:8080 - RAG 服务和 Web 界面：
http://localhost:8001
从源码启动 RAG 服务
uv sync 会创建根目录下的 .venv。不要在 hugegraph-llm 子目录另建一套环境，否则容易绕过 workspace 锁定的依赖。
安装 ML 依赖
示例脚本位于 hugegraph-ml/src/hugegraph_ml/examples/。
后续阅读
3.1 - HugeGraph-LLM
HugeGraph-LLM 用于知识图谱构建、GraphRAG 和自然语言图查询。演示服务把 Gradio 页面和 FastAPI 接口挂在同一个进程上，默认监听 8001 端口。
环境要求
AI 总结项目文档：Ask DeepWiki
- Python 3.10 或 3.11
uv0.7 或更高版本- HugeGraph Server 1.5 或更高版本
Docker Compose 部署
在 HugeGraph-AI 仓库根目录准备环境文件：
启动后可访问：
- HugeGraph Server：
http://localhost:8080 - RAG 服务和 Web 页面：
http://localhost:8001
从源码启动
依赖应从仓库根目录按 workspace 安装：
自定义监听地址和端口：
服务以 hugegraph-llm/.env 保存模型、HugeGraph 和登录配置。提示词放在 hugegraph-llm/src/hugegraph_llm/resources/demo/config_prompt.yaml。缺少文件时，配置代码会按默认值创建。
主要功能
构建 RAG 索引
Web 页面的第一个标签页可以处理文本或文件，并执行以下操作：
- 切分文本并写入 chunk 向量索引。
- 按给定 Schema 从文本抽取顶点和边。
- 将抽取结果写入 HugeGraph，并更新顶点向量索引。
Schema 可以是内联 JSON，也可以是现有图名。通过 REST API 使用图名时，必须同时传入匹配的 client_config.graph；内联 JSON 不会连接 HugeGraph，也不能附带 client_config。
GraphRAG
查询流程可以组合直接回答、chunk 向量召回和图召回。图召回先抽取关键词并匹配顶点，再尝试 Text2Gremlin；生成或执行失败时可回退到预定义的图遍历方式。请求参数可控制返回数量、向量距离阈值、模板数量和重排序方式。
Text2Gremlin
POST /text2gremlin 根据自然语言、图 Schema 和可选示例生成 Gremlin。自定义提示词必须保留 {query}、{schema}、{example} 和 {vertices} 四个占位符。
模型与向量后端
聊天、信息抽取和 Text2Gremlin 可以分别使用 OpenAI 兼容接口、Ollama 或 LiteLLM。嵌入模型也可以独立选择。默认向量索引使用 FAISS；安装 vectordb 可选依赖后，还可配置 Milvus 或 Qdrant：
完整环境变量见配置参考，HTTP 请求格式见REST API。
开发检查
3.2 - HugeGraph-ML
HugeGraph-ML 从 HugeGraph 读取图数据并转换为 DGL 图，供节点嵌入、节点分类和图分类等任务使用。模型实现位于 hugegraph-ml/src/hugegraph_ml/models/。
环境要求
- Python 3.10 或更高版本
- HugeGraph Server 1.0 或更高版本，推荐 1.5 及以上版本
uv0.7 或更高版本
安装
HugeGraph-ML 是根项目的路径依赖，但不属于 uv workspace members。应在仓库根目录选择 ml extra，不要在子目录建立另一套锁文件。
已实现模型
当前 README 列出的模型如下：
| 模型 | 主要用途 |
|---|---|
| AGNN、APPNP、ARMA、Cluster-GCN、DAGNN、DeeperGCN、GRAND、JKNet | 节点分类 |
| BGNN、CARE-GNN | 欺诈检测 |
| BGRL、DGI、GRACE | 表示学习 |
| DiffPool | 图分类 |
| GATNE、P-GNN、SEAL | 链接预测或网络嵌入 |
| C&S | 预测结果校正与平滑 |
源码中还包含 GIN 图分类实现和供下游分类使用的 MLPClassifier。模型数量会随版本变化，以 src/hugegraph_ml/models/ 为准。
DGI 节点嵌入示例
先把 DGL 的 Cora 数据集导入 HugeGraph：
读取图并训练 DGI：
完整脚本是 hugegraph-ml/src/hugegraph_ml/examples/dgi_example.py。
GRAND 节点分类示例
完整脚本是 hugegraph-ml/src/hugegraph_ml/examples/grand_example.py。
排查问题
- 连接失败：检查 HugeGraph Server 地址、端口和认证信息。
- Schema 不匹配：示例默认使用
CORA_vertex和CORA_edge，自有数据需要传入实际标签。 - DGL 或 PyTorch 导入失败：回到仓库根目录重新执行
uv sync --extra ml，并确认当前 Python 来自根目录.venv。
3.3 - HugeGraph-LLM 使用流程
本文说明 HugeGraph-LLM Web 页面的处理流程。服务启动方式见 HugeGraph-LLM。
1. 构建 RAG 索引
第一个标签页负责两类索引：
- 将文档切分后写入 chunk 向量索引。
- 按 Schema 从文档抽取顶点和边，写入 HugeGraph，并维护顶点向量索引。
flowchart TD
A[输入文档] --> B[文本切分]
B --> C[生成 chunk 向量]
C --> D[写入向量索引]
B --> E[LLM 按 Schema 抽取顶点和边]
E --> F[写入 HugeGraph]
F --> G[更新顶点向量索引]页面包含文档、Schema、抽取提示词和结果区域。常用操作有：
Import into Vector：切分文档并建立 chunk 向量索引。Extract Graph Data：按 Schema 抽取图数据。Load into GraphDB：把抽取结果写入 HugeGraph，并更新顶点向量。Update Vid Embedding：重新生成顶点向量。
页面还可以查看或清除 chunk 索引、顶点索引和图数据。清除操作会删除已有数据，执行前先确认当前图和索引是否仍被其他查询使用。
2. GraphRAG 查询
第二个标签页提供四种回答范围：
- 直接使用 LLM 回答。
- 只使用 chunk 向量召回。
- 只使用图召回。
- 合并图召回与向量召回。
flowchart TD
Q[问题] --> V[查询 chunk 向量索引]
Q --> K[抽取关键词]
K --> M[匹配图顶点]
M --> T[生成并执行 Gremlin]
T -->|失败| B[BFS 图遍历回退]
T --> R[整理图结果]
B --> R
V --> S[合并与重排序]
R --> S
S --> A[生成答案]图召回先用关键词精确匹配 HugeGraph 顶点，找不到时再用顶点向量做近似匹配。匹配结果会进入 Text2Gremlin；生成或执行失败时，流程可以回退到预定义的图遍历。
Template Num 控制 Text2Gremlin 使用的示例数量。小于等于 0 表示不提供模板，大于 0 表示从示例索引中取相应数量的相近模板。
3. Text2Gremlin
第三个标签页把自然语言转换成 Gremlin：
- 读取当前图的 Schema。
- 从示例向量索引取回相近的自然语言与 Gremlin 对。
- 把问题、Schema、示例和已匹配顶点填入提示词。
- 调用 LLM 生成 Gremlin，并按所选输出类型决定是否执行。
自定义提示词必须包含 {query}、{schema}、{example} 和 {vertices}。缺少任一占位符时，REST API 会拒绝请求。
4. 图工具与管理工具
Graph Tools 标签页用于直接执行图操作。Admin Tools 提供日志等管理能力。启用登录后，页面和 API 需要使用 USER_TOKEN；日志接口还要求单独配置安全的 ADMIN_TOKEN。
5. 提示词语言
在 hugegraph-llm/.env 中设置：
修改后重启服务。该配置选择内置提示词语言，不会自动翻译输入文档，也不是 /rag 请求体字段。
6. REST 调用
Web 页面和 REST API 使用同一套流程。需要程序集成时使用 /rag、/rag/graph、/graph/extract 和 /text2gremlin；请求结构见 REST API。
3.4 - 配置参考
HugeGraph-LLM 从 hugegraph-llm/.env 读取运行配置。提示词单独保存在 hugegraph-llm/src/hugegraph_llm/resources/demo/config_prompt.yaml，不会写入 .env。
运行以下命令可按配置类的默认值创建或更新文件：
.env 包含密钥和密码，不要提交到版本库。
基础选项
| 配置项 | 默认值 | 说明 |
|---|---|---|
LANGUAGE | EN | 提示词语言，可选 EN、CN |
CHAT_LLM_TYPE | openai | 回答模型，可选 openai、litellm、ollama/local |
EXTRACT_LLM_TYPE | openai | 信息抽取模型，取值同上 |
TEXT2GQL_LLM_TYPE | openai | Text2Gremlin 模型，取值同上 |
EMBEDDING_TYPE | openai | 嵌入模型，取值同上，也可以留空 |
RERANKER_TYPE | 空 | 可选 cohere、siliconflow |
KEYWORD_EXTRACT_TYPE | llm | 可选 llm、textrank、hybrid |
WINDOW_SIZE | 3 | TextRank 滑窗，范围 1 到 10 |
HYBRID_LLM_WEIGHTS | 0.5 | hybrid 模式中 LLM 结果的权重，范围 0 到 1 |
OpenAI 兼容接口
聊天、抽取和 Text2Gremlin 可以使用不同端点、密钥和模型。
| 用途 | API 地址 | 密钥 | 模型 | 最大 token 默认值 |
|---|---|---|---|---|
| 回答 | OPENAI_CHAT_API_BASE | OPENAI_CHAT_API_KEY | OPENAI_CHAT_LANGUAGE_MODEL | OPENAI_CHAT_TOKENS=8192 |
| 抽取 | OPENAI_EXTRACT_API_BASE | OPENAI_EXTRACT_API_KEY | OPENAI_EXTRACT_LANGUAGE_MODEL | OPENAI_EXTRACT_TOKENS=256 |
| Text2Gremlin | OPENAI_TEXT2GQL_API_BASE | OPENAI_TEXT2GQL_API_KEY | OPENAI_TEXT2GQL_LANGUAGE_MODEL | OPENAI_TEXT2GQL_TOKENS=4096 |
| 嵌入 | OPENAI_EMBEDDING_API_BASE | OPENAI_EMBEDDING_API_KEY | OPENAI_EMBEDDING_MODEL | 不适用 |
API 地址默认是 https://api.openai.com/v1；三个语言模型默认是 gpt-4.1-mini，嵌入模型默认是 text-embedding-3-small。
OPENAI_BASE_URL 和 OPENAI_API_KEY 可作为通用回退值。嵌入模型另有 OPENAI_EMBEDDING_BASE_URL 和 OPENAI_EMBEDDING_API_KEY 回退值。
LiteLLM
| 用途 | API 地址 | 密钥 | 模型 | 最大 token 默认值 |
|---|---|---|---|---|
| 回答 | LITELLM_CHAT_API_BASE | LITELLM_CHAT_API_KEY | LITELLM_CHAT_LANGUAGE_MODEL | LITELLM_CHAT_TOKENS=8192 |
| 抽取 | LITELLM_EXTRACT_API_BASE | LITELLM_EXTRACT_API_KEY | LITELLM_EXTRACT_LANGUAGE_MODEL | LITELLM_EXTRACT_TOKENS=256 |
| Text2Gremlin | LITELLM_TEXT2GQL_API_BASE | LITELLM_TEXT2GQL_API_KEY | LITELLM_TEXT2GQL_LANGUAGE_MODEL | LITELLM_TEXT2GQL_TOKENS=4096 |
| 嵌入 | LITELLM_EMBEDDING_API_BASE | LITELLM_EMBEDDING_API_KEY | LITELLM_EMBEDDING_MODEL | 不适用 |
三个语言模型默认是 openai/gpt-4.1-mini，嵌入模型默认是 openai/text-embedding-3-small。模型名通常使用 供应商/模型 格式，具体取值由 LiteLLM 服务决定。
Ollama
| 用途 | 主机 | 端口 | 模型 |
|---|---|---|---|
| 回答 | OLLAMA_CHAT_HOST | OLLAMA_CHAT_PORT | OLLAMA_CHAT_LANGUAGE_MODEL |
| 抽取 | OLLAMA_EXTRACT_HOST | OLLAMA_EXTRACT_PORT | OLLAMA_EXTRACT_LANGUAGE_MODEL |
| Text2Gremlin | OLLAMA_TEXT2GQL_HOST | OLLAMA_TEXT2GQL_PORT | OLLAMA_TEXT2GQL_LANGUAGE_MODEL |
| 嵌入 | OLLAMA_EMBEDDING_HOST | OLLAMA_EMBEDDING_PORT | OLLAMA_EMBEDDING_MODEL |
主机默认是 127.0.0.1，端口默认是 11434，模型名没有默认值。使用前先在 Ollama 中拉取对应模型。
重排序
| 配置项 | 默认值 | 说明 |
|---|---|---|
COHERE_BASE_URL | https://api.cohere.com/v1/rerank | Cohere rerank 接口；CO_API_URL 可作为回退值 |
RERANKER_API_KEY | 空 | Cohere 或 SiliconFlow 密钥 |
RERANKER_MODEL | 空 | 服务端支持的模型名 |
HugeGraph 连接与召回限制
| 配置项 | 默认值 | 说明 |
|---|---|---|
GRAPH_URL | 127.0.0.1:8080 | HugeGraph 地址，不拆分为 IP 和端口 |
GRAPH_NAME | hugegraph | 图名 |
GRAPH_USER | admin | 用户名 |
GRAPH_PWD | xxx | 密码 |
GRAPH_SPACE | 空 | GraphSpace 名称 |
LIMIT_PROPERTY | False | 是否限制返回属性；配置类按字符串读取 |
MAX_GRAPH_PATH | 10 | 最大图路径长度 |
MAX_GRAPH_ITEMS | 30 | 图召回的最大项目数 |
EDGE_LIMIT_PRE_LABEL | 8 | 每个边标签的返回上限 |
VECTOR_DIS_THRESHOLD | 0.9 | 向量距离阈值；超过阈值的结果会被忽略 |
TOPK_PER_KEYWORD | 1 | 每个关键词的候选数 |
TOPK_RETURN_RESULTS | 20 | 重排序后返回的结果数 |
外部向量数据库
默认实现可以使用本地 FAISS。启用可选依赖后还可配置：
| 配置项 | 默认值 |
|---|---|
QDRANT_HOST | 空 |
QDRANT_PORT | 6333 |
QDRANT_API_KEY | 空 |
MILVUS_HOST | 空 |
MILVUS_PORT | 19530 |
MILVUS_USER | 空 |
MILVUS_PASSWORD | 空 |
安装对应依赖：
登录与日志接口
| 配置项 | 默认值 | 说明 |
|---|---|---|
ENABLE_LOGIN | False | 是否要求 Bearer token；配置类按字符串读取 |
USER_TOKEN | 4321 | Web 页面和普通 API 的 token |
ADMIN_TOKEN | xxxx | /logs 使用的管理员 token |
ADMIN_TOKEN 为空或仍为 xxxx 时，/logs 会直接返回 403。生产环境应同时替换用户 token 和管理员 token。
最小 OpenAI 配置
配置加载
配置类先提供代码默认值，再从 .env 和进程环境读取覆盖值。Web 页面和配置 API 可以在运行时更新当前设置，并把受支持的字段同步回 .env。手工改动 .env 后应重启服务；提示词 YAML 可由页面加载逻辑刷新。
配置定义位于：
hugegraph-llm/src/hugegraph_llm/config/llm_config.pyhugegraph-llm/src/hugegraph_llm/config/hugegraph_config.pyhugegraph-llm/src/hugegraph_llm/config/admin_config.pyhugegraph-llm/src/hugegraph_llm/config/prompt_config.py
3.5 - HugeGraph-LLM REST API
HugeGraph-LLM 演示进程同时提供 Web 页面和 REST API。默认地址是 http://localhost:8001：
认证
在 .env 中启用登录：
启用后，请求需要 Bearer token：
RAG
POST /rag
根据开关返回一种或多种回答。未显式指定时只启用 graph_only。
响应只包含已启用的回答字段：
其他可选参数包括 graph_ratio、rerank_method（bleu 或 reranker）、near_neighbor_first、custom_priority_info，以及三类自定义提示词。
POST /rag/graph
只执行图召回，不生成最终自然语言答案：
响应的 graph_recall 可能包含 keywords、match_vids、gremlin、graph_result 和 vertex_degree_list。设置 get_vertex_only=true 可在顶点匹配后提前返回。
图抽取
POST /graph/extract
使用内联 Schema 时不会连接 HugeGraph：
texts 可以是字符串或字符串数组。language 可选 zh、en，split_type 可选 document、paragraph、sentence。
若 schema 传现有图名，必须同时传入 client_config，且 client_config.graph 必须和图名相同：
成功响应固定包含 status、result.vertices、result.edges、warnings 和 meta。
Text2Gremlin
POST /text2gremlin
output_types 可包含：
match_resulttemplate_gremlinraw_gremlintemplate_execution_resultraw_execution_result
省略该字段时默认只返回 template_gremlin；传空数组表示由实现返回全部输出。自定义 gremlin_prompt 必须包含 {query}、{schema}、{example} 和 {vertices}。
运行时配置
POST /config/graph
POST /config/llm 与 POST /config/embedding
两个端点使用同一个请求模型。OpenAI 或 LiteLLM 示例：
Ollama 请求仍要提供公共字段；api_key 和 api_base 可传空字符串：
POST /config/rerank
reranker_type 可选 cohere、siliconflow。Cohere 还可以传 cohere_base_url。
这些配置端点会改动进程当前配置，并可能同步到 .env。/rag、/rag/graph 和 /text2gremlin 的 client_config 只在单次请求期间覆盖 HugeGraph 连接；当前实现仍会临时改动进程全局设置，不适合用不同连接并发发起长请求。
日志
POST /logs
该接口要求 .env 中的 ADMIN_TOKEN 已改成安全值。请求体示例：
log_file 只能是 logs/ 目录下的文件名，不能包含路径分隔符。
4 - HugeGraph 图计算（OLAP）
HugeGraph-Computer 仓库包含两套 OLAP 系统：Java 实现的分布式 BSP 框架 Computer，以及 Go 实现的内存图计算平台 Vermeer。
DeepWiki 提供实时更新的项目文档，内容更全面准确，适合快速了解项目最新情况。
4.1 - HugeGraph-Vermeer Quick Start
一、Vermeer 概述
1.1 运行架构
Vermeer 是一个 Go编写的高性能内存优先的图计算框架 (一次启动，任意执行)，支持 15+ OLAP 图算法的极速计算 (大部分秒~分钟级别完成执行)，包含 master 和 worker 两种角色。master 目前只有一个 (可增加 HA)，worker 可以有多个。
master 是负责通信、转发、汇总的节点，计算量和占用资源量较少。worker 是计算节点，用于存储图数据和运行计算任务，占用大量内存和 cpu。grpc 和 rest 模块分别负责内部通信和外部调用。
该框架的运行配置可以通过命令行参数传入，也可以通过位于 config/ 目录下的配置文件指定，--env 参数可以指定使用哪个配置文件，例如 --env=master 指定使用 master.ini。需要注意 master 需要指定监听的端口号，worker 需要指定监听端口号和 master 的 ip:port。
1.2 运行方法
- 方案一：Docker Compose（推荐）
确保docker-compose.yaml存在于您的项目根目录中。如果没有，以下是一个示例：
修改 docker-compose.yaml
- Volume：例如将两处 ~/:/go/bin/config 改为 /home/user/config:/go/bin/config（或您自己的配置目录）。
- Subnet：根据实际情况修改子网IP。请注意，每个容器需要访问的端口在config文件中指定，具体请参照项目
config文件夹下内容。
在项目目录构建镜像并启动（或者先用 docker build 再 docker-compose up）
查看日志 / 停止 / 删除：
- 方案二：通过 docker run 单独启动（手动创建网络并分配静态 IP）
确保CONFIG_DIR对Docker进程具有适当的读取/执行权限。
构建镜像：
创建自定义 bridge 网络（一次性操作）：
运行 master（调整 CONFIG_DIR 为您的绝对配置路径，可以根据实际情况调整IP）：
运行 worker：
查看日志 / 停止 / 删除：
- 方案三：从源码构建
构建。具体请参照 Vermeer Readme。
在进入文件夹目录后输入 ./vermeer --env=master 或 ./vermeer --env=worker01
二、任务创建类 rest api
2.1 简介
此类 rest api 提供所有创建任务的功能，包括读取图数据和多种计算功能，提供异步返回和同步返回两种接口。返回的内容均包含所创建任务的信息。使用 vermeer 的整体流程是先创建读取图的任务，待图读取完毕后创建计算任务执行计算。图不会自动被删除，在一个图上运行多个计算任务无需多次重复读取，如需删除可用删除图接口。任务状态可分为读取任务状态和计算任务状态。通常情况下客户端仅需了解创建、任务中、任务结束和任务错误四种状态。图状态是图是否可用的判断依据，若图正在读取中或图状态错误，无法使用该图创建计算任务。图删除接口仅在 loaded 和 error 状态且该图无计算任务时可用。
可以使用的 url 如下：
- 异步返回接口 POST http://master_ip:port/tasks/create 仅返回任务创建是否成功，需通过主动查询任务状态判断是否完成。
- 同步返回接口 POST http://master_ip:port/tasks/create/sync 在任务结束后返回。
2.2 加载图数据
具体参数参考 Vermeer 参数列表文档。
vermeer提供三种加载方式：
- 从本地加载
可以预先获取数据集，例如 twitter-2010 数据集。获取方式：https://snap.stanford.edu/data/twitter-2010.html，第一个 twitter-2010.txt.gz 即可。
request 示例：
- 从hugegraph加载
request 示例：
⚠️ 安全警告：切勿在配置文件或代码中存储真实密码。请改用环境变量或安全的凭据管理系统。
- 从hdfs加载
request 示例：
2.3 输出计算结果
所有的 vermeer 计算任务均支持多种结果输出方式，可自定义输出方式：local、hdfs、afs 或 hugegraph，在发送请求时的 params 参数下加入对应参数，即可生效。指定 output.need_statistics 为 1 时，支持计算结果统计信息输出，结果会写在接口任务信息内。统计模式算子目前支持 “count” 和 “modularity” 。但仅针对社区发现算法适用。
具体参数参考 Vermeer 参数列表文档。
request 示例：
三、支持的算法
3.1 PageRank
PageRank 算法又称网页排名算法，是一种由搜索引擎根据网页（节点）之间相互的超链接进行计算的技
术，用来体现网页（节点）的相关性和重要性。
- 如果一个网页被很多其他网页链接到，说明这个网页比较重要，也就是其 PageRank 值会相对较高。
- 如果一个 PageRank 值很高的网页链接到其他网页，那么被链接到的网页的 PageRank 值会相应地提高。
PageRank 算法适用于网页排序、社交网络重点人物发掘等场景。
request 示例：
3.2 WCC（弱连通分量）
弱连通分量，计算无向图中所有联通的子图，输出各顶点所属的弱联通子图 id，表明各个点之间的连通性，区分不同的连通社区。
request 示例：
3.3 LPA（标签传播）
标签传递算法，是一种图聚类算法，常用在社交网络中，用于发现潜在的社区。
request 示例：
3.4 Degree Centrality（度中心性）
度中心性算法，算法用于计算图中每个节点的度中心性值，支持无向图和有向图。度中心性是衡量节点重要性的重要指标，节点与其它节点的边越多，则节点的度中心性值越大，节点在图中的重要性也就越高。在无向图中，度中心性的计算是基于边信息统计节点出现次数，得出节点的度中心性的值，在有向图中则基于边的方向进行筛选，基于输入边或输出边信息统计节点出现次数，得到节点的入度值或出度值。它表明各个点的重要性，一般越重要的点度数越高。
request 示例：
3.5 Closeness Centrality（紧密中心性）
紧密中心性（Closeness Centrality）用于计算一个节点到所有其他可达节点的最短距离的倒数，进行累积后归一化的值。紧密中心度可以用来衡量信息从该节点传输到其他节点的时间长短。节点的“Closeness Centrality”越大，其在所在图中的位置越靠近中心，适用于社交网络中关键节点发掘等场景。
request 示例：
3.6 Betweenness Centrality（中介中心性算法）
中介中心性算法（Betweeness Centrality）判断一个节点具有"桥梁"节点的值，值越大说明它作为图中两点间必经路径的可能性越大，典型的例子包括社交网络中的共同关注的人。适用于衡量社群围绕某个节点的聚集程度。
request 示例：
3.7 Triangle Count（三角形计数）
三角形计数算法，用于计算通过每个顶点的三角形个数，适用于计算用户之间的关系，关联性是不是成三角形。三角形越多，代表图中节点关联程度越高，组织关系越严密。社交网络中的三角形表示存在有凝聚力的社区，识别三角形有助于理解网络中个人或群体的聚类和相互联系。在金融网络或交易网络中，三角形的存在可能表示存在可疑或欺诈活动，三角形计数可以帮助识别可能需要进一步调查的交易模式。
输出的结果为 每个顶点对应一个 Triangle Count，即为每个顶点所在三角形的个数。
注：该算法为无向图算法，忽略边的方向。
request 示例：
3.8 K-Core
K-Core 算法，标记所有度数为 K 的顶点，适用于图的剪枝，查找图的核心部分。
request 示例：
3.9 SSSP（单元最短路径）
单源最短路径算法，求一个点到其他所有点的最短距离。
request 示例：
3.10 KOUT
以一个点为起点，获取这个点的 k 层的节点。
request 示例：
3.11 Louvain
Louvain 算法是一种基于模块度的社区发现算法。其基本思想是网络中节点尝试遍历所有邻居的社区标签，并选择最大化模块度增量的社区标签。在最大化模块度之后，每个社区看成一个新的节点，重复直到模块度不再增大。
Vermeer 上实现的分布式 Louvain 算法受节点顺序、并行计算等因素影响，并且由于 Louvain 算法由于其遍历顺序的随机导致社区压缩也具有一定的随机性，导致重复多次执行可能存在不同的结果。但整体趋势不会有大的变化。
request 示例：
3.12 Jaccard 相似度系数
Jaccard index , 又称为 Jaccard 相似系数（Jaccard similarity coefficient）用于比较有限样本集之间的相似性与差异性。Jaccard 系数值越大，样本相似度越高。用于计算一个给定的源点，与图中其他所有点的 Jaccard 相似系数。
request 示例：
3.13 Personalized PageRank
个性化的 pagerank 的目标是要计算所有节点相对于用户 u 的相关度。从用户 u 对应的节点开始游走，每到一个节点都以 1-d 的概率停止游走并从 u 重新开始，或者以 d 的概率继续游走，从当前节点指向的节点中按照均匀分布随机选择一个节点往下游走。用于给定一个起点，计算此起点开始游走的个性化 pagerank 得分。适用于社交推荐等场景。
由于计算需要使用出度，需要在读取图时需要设置 load.use_out_degree 为 1。
request 示例：
3.14 全图 Kout
计算图的所有节点的k度邻居（不包含自己以及1～k-1度的邻居），由于全图kout算法内存膨胀比较厉害，目前k限制在1和2，另外，全局kout算法支持过滤功能( 参数如：“compute.filter”:“risk_level==1”),在计算第k度的是时候进行过滤条件的判断，符合过滤条件的进入最终结果集，算法最终输出是符合条件的邻居个数。
request 示例：
3.15 集聚系数 clustering coefficient
集聚系数表示一个图中节点聚集程度的系数。在现实的网络中，尤其是在特定的网络中，由于相对高密度连接点的关系，节点总是趋向于建立一组严密的组织关系。集聚系数算法（Cluster Coefficient）用于计算图中节点的聚集程度。本算法为局部集聚系数。局部集聚系数可以测量图中每一个结点附近的集聚程度。
request 示例：
3.16 SCC（强连通分量）
在有向图的数学理论中，如果一个图的每一个顶点都可从该图其他任意一点到达，则称该图是强连通的。在任意有向图中能够实现强连通的部分我们称其为强连通分量。它表明各个点之间的连通性，区分不同的连通社区。
🚧, 后续随时更新完善，欢迎随时提出建议和意见。
4.2 - HugeGraph-Computer Quick Start
1 HugeGraph-Computer 概述
HugeGraph-Computer 是分布式图处理系统 (OLAP). 它是 Pregel的一个实现。它可以运行在 Kubernetes(K8s)/Yarn 上。(它侧重可支持百亿~千亿的图数据量下进行图计算, 会使用磁盘进行排序和加速, 这是它和 Vermeer 相对最大的区别之一)
特性
- 支持分布式 MPP 图计算，集成 HugeGraph 作为图输入输出存储。
- 算法基于 BSP(Bulk Synchronous Parallel) 模型，通过多次并行迭代进行计算，每一次迭代都是一次超步。
- 自动内存管理。该框架永远不会出现 OOM（内存不足），因为如果它没有足够的内存来容纳所有数据，它会将一些数据拆分到磁盘。
- 边的部分或超级节点的消息可以在内存中，所以你永远不会丢失它。
- 您可以从 HDFS 或 HugeGraph 或任何其他系统加载数据。
- 您可以将结果输出到 HDFS 或 HugeGraph，或任何其他系统。
- 易于开发新算法。您只需要像在单个服务器中一样专注于仅顶点处理，而不必担心消息传输和内存存储管理。
2 依赖
2.1 安装 Java 11 (JDK 11)
必须在 ≥ Java 11 的环境上启动 Computer，然后自行配置。
在往下阅读之前务必执行 java -version 命令查看 jdk 版本
3 开始
3.1 在本地运行 PageRank 算法
要使用 HugeGraph-Computer 运行算法，必须装有 Java 11 或更高版本。
还需要首先部署 HugeGraph-Server 和 Etcd.
有两种方式可以获取 HugeGraph-Computer：
- 下载已编译的压缩包
- 克隆源码编译打包
3.1.1 下载已编译的压缩包
下载最新版本的 HugeGraph-Computer release 包：
3.1.2 克隆源码编译打包
克隆最新版本的 HugeGraph-Computer 源码包：
编译生成 tar 包：
3.1.3 启动 master 节点
您可以使用
-c参数指定配置文件，更多 computer 配置请看：Computer Config Options
3.1.4 启动 worker 节点
3.1.5 查询算法结果
2.5.1 为 server 启用 OLAP 索引查询
如果没有启用 OLAP 索引，则需要启用，更多参考：modify-graphs-read-mode
3.1.5.2 查询 page_rank 属性值：
3.2 在 Kubernetes 中运行 PageRank 算法
要使用 HugeGraph-Computer 运行算法，您需要先部署 HugeGraph-Server
3.2.1 安装 HugeGraph-Computer CRD
3.2.2 显示 CRD
3.2.3 安装 hugegraph-computer-operator&etcd-server
3.2.4 等待 hugegraph-computer-operator&etcd-server 部署完成
3.2.5 提交作业
更多 computer crd spec 请看：Computer CRD
更多 Computer 配置请看：Computer Config Options
3.2.6 显示作业
3.2.7 显示节点日志
3.2.8 显示作业的成功事件
NOTE: it will only be saved for one hour
3.2.9 查询算法结果
如果输出到 Hugegraph-Server 则与 Locally 模式一致，如果输出到 HDFS ，请检查 hugegraph-computerresults{jobId}目录下的结果文件。
4 内置算法文档
4.1 支持的算法列表：
中心性算法：
- PageRank
- BetweennessCentrality
- ClosenessCentrality
- DegreeCentrality
社区算法：
- ClusteringCoefficient
- Kcore
- Lpa
- TriangleCount
- Wcc
路径算法：
- RingsDetection
- RingsDetectionWithFilter
更多算法请看：Built-In algorithms
4.2 算法描述
TODO
5 算法开发指南
TODO
6 注意事项
- 如果 computer-k8s 模块下面的某些类不存在，你需要运行
mvn compile来提前生成对应的类。
4.3 - HugeGraph-Computer 配置参考
Computer 配置选项
表格中的默认值来自 computer-api 模块的 ComputerOptions.java。分发包的 conf/computer.properties 显式覆盖某项时，表格以“代码默认值（打包：实际值）”标注；程序启动后以配置文件中的值为准。
1. 基础配置
HugeGraph-Computer 核心作业设置。
| 配置项 | 默认值 | 说明 |
|---|---|---|
| hugegraph.url | http://127.0.0.1:8080 | HugeGraph 服务器 URL,用于加载数据和写回结果。 |
| hugegraph.name | hugegraph | 图名称,用于加载数据和写回结果。 |
| hugegraph.username | "" (空) | HugeGraph 认证用户名(如果未启用认证则留空)。 |
| hugegraph.password | "" (空) | HugeGraph 认证密码(如果未启用认证则留空)。 |
| job.id | local_0001 (打包: local_001) | YARN 集群或 K8s 集群上的作业标识符。 |
| job.namespace | "" (空) | 作业命名空间，可以分隔不同的数据源。该项由运行系统管理。 |
| job.workers_count | 1 | 执行一个图算法作业的 Worker 数量。在 K8s 中由 Operator 设置。 |
| job.partitions_count | 1 | 执行一个图算法作业的分区数量。 |
| job.partitions_thread_nums | 4 | 分区并行计算的线程数量。 |
2. 算法配置
计算逻辑的算法特定配置。
| 配置项 | 默认值 | 说明 |
|---|---|---|
| algorithm.params_class | ComputerOptions.Null 占位类 | 必填。用于在算法运行前传递算法参数的类。 |
| algorithm.result_class | ComputerOptions.Null 占位类 | 顶点值的类，用于存储顶点的计算结果。 |
| algorithm.message_class | ComputerOptions.Null 占位类 | 计算顶点时传递的消息类。 |
3. 输入配置
从 HugeGraph 或其他数据源加载输入数据的配置。
3.1 输入源
| 配置项 | 默认值 | 说明 |
|---|---|---|
| input.source_type | hugegraph-server | 加载输入数据的源类型,允许值:[‘hugegraph-server’, ‘hugegraph-loader’]。‘hugegraph-loader’ 表示使用 hugegraph-loader 从 HDFS 或文件加载数据。如果使用 ‘hugegraph-loader’,请配置 ‘input.loader_struct_path’ 和 ‘input.loader_schema_path’。 |
| input.loader_struct_path | "" (空) | Loader 输入的结构路径，仅在 input.source_type=hugegraph-loader 时生效。 |
| input.loader_schema_path | "" (空) | Loader 输入的 Schema 路径，仅在 input.source_type=hugegraph-loader 时生效。 |
3.2 输入分片
| 配置项 | 默认值 | 说明 |
|---|---|---|
| input.split_size | 1048576 (1 MB) | 输入分片大小(字节)。 |
| input.split_max_splits | 10000000 | 最大输入分片数量。 |
| input.split_page_size | 500 | 流式加载输入分片数据的页面大小。 |
| input.split_fetch_timeout | 300 | 获取输入分片的超时时间(秒)。 |
3.3 输入处理
| 配置项 | 默认值 | 说明 |
|---|---|---|
| input.filter_class | org.apache.hugegraph.computer.core.input.filter.DefaultInputFilter | 创建输入过滤器对象的类。输入过滤器用于根据用户需求过滤顶点边。 |
| input.edge_direction | OUT | 要加载的边的方向,允许值:[OUT, IN, BOTH]。当值为 BOTH 时,将加载 OUT 和 IN 两个方向的边。 |
| input.edge_freq | MULTIPLE | 一对顶点之间可以存在的边的频率,允许值:[SINGLE, SINGLE_PER_LABEL, MULTIPLE]。SINGLE 表示一对顶点之间只能存在一条边(通过 sourceId + targetId 标识);SINGLE_PER_LABEL 表示每个边标签在一对顶点之间可以有一条边(通过 sourceId + edgeLabel + targetId 标识);MULTIPLE 表示一对顶点之间可以存在多条边(通过 sourceId + edgeLabel + sortValues + targetId 标识)。 |
| input.max_edges_in_one_vertex | 200 | 允许附加到一个顶点的最大邻接边数量。邻接边将作为一个批处理单元一起存储和传输。 |
3.4 输入性能
| 配置项 | 默认值 | 说明 |
|---|---|---|
| input.send_thread_nums | 4 | 并行发送顶点或边的线程数量。 |
4. 快照与存储配置
HugeGraph-Computer 支持快照功能,可将顶点/边分区保存到本地存储或 MinIO 对象存储,用于断点恢复或加速重复计算。
4.1 基础快照配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
| snapshot.write | false | 是否写入输入顶点/边分区的快照。 |
| snapshot.load | false | 是否从顶点/边分区的快照加载。 |
| snapshot.name | "" (空) | 用户自定义的快照名称,用于区分不同的快照。 |
4.2 MinIO 集成(可选)
MinIO 可用作 K8s 部署中快照的分布式对象存储后端。
| 配置项 | 默认值 | 说明 |
|---|---|---|
| snapshot.minio_endpoint | "" (空) | MinIO 服务端点(例如 http://minio:9000)。使用 MinIO 时必填。 |
| snapshot.minio_access_key | minioadmin | MinIO 认证访问密钥。 |
| snapshot.minio_secret_key | minioadmin | MinIO 认证密钥。 |
| snapshot.minio_bucket_name | "" (空) | 用于存储快照数据的 MinIO 存储桶名称。 |
使用场景:
- 断点恢复:作业失败后从快照恢复,避免重新加载数据
- 重复计算:多次运行同一算法时从快照加载数据以加速启动
- A/B 测试:保存同一数据集的多个快照版本,测试不同的算法参数
示例:本地快照(在 computer.properties 中):
示例:MinIO 快照(在 K8s CRD computerConf 中):
5. Worker 与 Master 配置
Worker 和 Master 计算逻辑的配置。
5.1 Master 配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
| master.computation_class | org.apache.hugegraph.computer.core.master.DefaultMasterComputation | Master 计算是可以决定是否继续下一个超步的计算。它在每个超步结束时在 master 上运行。 |
5.2 Worker 计算
| 配置项 | 默认值 | 说明 |
|---|---|---|
| worker.computation_class | org.apache.hugegraph.computer.core.config.Null | 创建 worker 计算对象的类。Worker 计算用于在每个超步中计算每个顶点。 |
| worker.combiner_class | org.apache.hugegraph.computer.core.config.Null | Combiner 可以将消息组合为一个顶点的一个值。例如,PageRank 算法可以将一个顶点的消息组合为一个求和值。 |
| worker.partitioner | org.apache.hugegraph.computer.core.graph.partition.HashPartitioner | 分区器,决定顶点应该在哪个分区中,以及分区应该在哪个 worker 中。 |
5.3 Worker 组合器
| 配置项 | 默认值 | 说明 |
|---|---|---|
| worker.vertex_properties_combiner_class | org.apache.hugegraph.computer.core.combiner.OverwritePropertiesCombiner | 组合器可以在输入步骤将同一顶点的多个属性组合为一个属性。 |
| worker.edge_properties_combiner_class | org.apache.hugegraph.computer.core.combiner.OverwritePropertiesCombiner | 组合器可以在输入步骤将同一边的多个属性组合为一个属性。 |
5.4 Worker 缓冲区
| 配置项 | 默认值 | 说明 |
|---|---|---|
| worker.received_buffers_bytes_limit | 104857600 (100 MB) | 接收数据缓冲区的限制字节数。所有缓冲区的总大小不能超过此限制。如果接收缓冲区达到此限制,它们将被合并到文件中(溢出到磁盘)。 |
| worker.write_buffer_capacity | 52428800 (50 MB) | 用于存储顶点或消息的写缓冲区的初始大小。 |
| worker.write_buffer_threshold | 52428800 (50 MB) | 写缓冲区的阈值。超过它将触发排序。写缓冲区用于存储顶点或消息。 |
5.5 Worker 数据与超时
| 配置项 | 默认值 | 说明 |
|---|---|---|
| worker.data_dirs | [jobs] | 用逗号分隔的目录,接收的顶点和消息可以持久化到其中。 |
| worker.wait_sort_timeout | 600000 (10 分钟) | 消息处理程序等待排序线程对一批缓冲区进行排序的最大超时时间(毫秒)。 |
| worker.wait_finish_messages_timeout | 86400000 (24 小时) | 消息处理程序等待所有 worker 完成消息的最大超时时间(毫秒)。 |
6. I/O 与输出配置
输出计算结果的配置。
6.1 输出类与结果
| 配置项 | 默认值 | 说明 |
|---|---|---|
| output.output_class | org.apache.hugegraph.computer.core.output.LogOutput | 输出每个顶点计算结果的类。在迭代计算后调用。 |
| output.result_name | value | 该值由 WORKER_COMPUTATION_CLASS 创建的实例的 #name() 动态分配。 |
| output.result_write_type | OLAP_COMMON | 输出到 HugeGraph 的结果写入类型,允许值:[OLAP_COMMON, OLAP_SECONDARY, OLAP_RANGE]。 |
6.2 输出行为
| 配置项 | 默认值 | 说明 |
|---|---|---|
| output.with_adjacent_edges | false | 是否输出顶点的邻接边。 |
| output.with_vertex_properties | false | 是否输出顶点的属性。 |
| output.with_edge_properties | false | 是否输出边的属性。 |
6.3 批量输出
| 配置项 | 默认值 | 说明 |
|---|---|---|
| output.batch_size | 500 | 输出的批处理大小。 |
| output.batch_threads | 1 | 用于批量输出的线程数量。 |
| output.single_threads | 1 | 用于单个输出的线程数量。 |
6.4 HDFS 输出
| 配置项 | 默认值 | 说明 |
|---|---|---|
| output.hdfs_url | hdfs://127.0.0.1:9000 | 输出的 HDFS URL。 |
| output.hdfs_user | hadoop | 输出的 HDFS 用户。 |
| output.hdfs_path_prefix | /hugegraph-computer/results | HDFS 输出结果的目录。 |
| output.hdfs_delimiter | , (逗号) | HDFS 输出的分隔符。 |
| output.hdfs_merge_partitions | true | 是否合并多个分区的输出文件。 |
| output.hdfs_replication | 3 | HDFS 的副本数。 |
| output.hdfs_core_site_path | "" (空) | HDFS core site 路径。 |
| output.hdfs_site_path | "" (空) | HDFS site 路径。 |
| output.hdfs_kerberos_enable | false | 是否为 HDFS 启用 Kerberos 认证。 |
| output.hdfs_kerberos_principal | "" (空) | HDFS 的 Kerberos 认证 principal。 |
| output.hdfs_kerberos_keytab | "" (空) | HDFS 的 Kerberos 认证 keytab 文件。 |
| output.hdfs_krb5_conf | /etc/krb5.conf | Kerberos 配置文件路径。 |
6.5 重试与超时
| 配置项 | 默认值 | 说明 |
|---|---|---|
| output.retry_times | 3 | 输出失败时的重试次数。 |
| output.retry_interval | 10 | 输出失败时的重试间隔(秒)。 |
| output.thread_pool_shutdown_timeout | 60 | 输出线程池关闭的超时时间(秒)。 |
7. 网络与传输配置
Worker 和 Master 之间网络通信的配置。
7.1 服务器配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
| transport.server_host | 127.0.0.1 | 监听传输数据的主机名或 IP，由运行系统管理。 |
| transport.server_port | 0 | 监听传输数据的端口；0 表示分配随机端口。该项由运行系统管理。 |
| transport.server_threads | 4 | 服务器传输线程的数量。 |
7.2 客户端配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
| transport.client_threads | 4 | 客户端传输线程的数量。 |
| transport.client_connect_timeout | 3000 | 客户端连接到服务器的超时时间(毫秒)。 |
7.3 协议配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
| transport.provider_class | org.apache.hugegraph.computer.core.network.netty.NettyTransportProvider | 传输提供程序,目前仅支持 Netty。 |
| transport.io_mode | AUTO | 网络 IO 模式,允许值:[NIO, EPOLL, AUTO]。AUTO 表示自动选择适当的模式。 |
| transport.tcp_keep_alive | true | 是否启用 TCP keep-alive。 |
| transport.transport_epoll_lt | false | 是否启用 EPOLL 水平触发(仅在 io_mode=EPOLL 时有效)。 |
7.4 缓冲区配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
| transport.send_buffer_size | 0 | Socket 发送缓冲区大小(字节)。0 表示使用系统默认值。 |
| transport.receive_buffer_size | 0 | Socket 接收缓冲区大小(字节)。0 表示使用系统默认值。 |
| transport.write_buffer_high_mark | 67108864 (64 MB) | 写缓冲区的高水位标记(字节)。如果排队字节数 > write_buffer_high_mark,将触发发送不可用。 |
| transport.write_buffer_low_mark | 33554432 (32 MB) | 写缓冲区的低水位标记(字节)。如果排队字节数 < write_buffer_low_mark,将触发发送可用。 |
7.5 流量控制
| 配置项 | 默认值 | 说明 |
|---|---|---|
| transport.max_pending_requests | 8 | 客户端未接收 ACK 的最大数量。如果未接收 ACK 的数量 >= max_pending_requests,将触发发送不可用。 |
| transport.min_pending_requests | 6 | 客户端未接收 ACK 的最小数量。如果未接收 ACK 的数量 < min_pending_requests,将触发发送可用。 |
| transport.min_ack_interval | 200 | 服务器回复 ACK 的最小间隔(毫秒)。 |
7.6 超时配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
| transport.close_timeout | 10000 | 关闭服务器或关闭客户端的超时时间(毫秒)。 |
| transport.sync_request_timeout | 10000 | 发送同步请求后等待响应的超时时间(毫秒)。 |
| transport.finish_session_timeout | 0 | 完成会话的超时时间(毫秒)。0 表示使用 (transport.sync_request_timeout × transport.max_pending_requests)。 |
| transport.write_socket_timeout | 3000 | 将数据写入 socket 缓冲区的超时时间(毫秒)。 |
| transport.server_idle_timeout | 360000 (6 分钟) | 服务器空闲的最大超时时间(毫秒)。 |
7.7 心跳配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
| transport.heartbeat_interval | 20000 (20 秒) | 客户端心跳之间的最小间隔(毫秒)。 |
| transport.max_timeout_heartbeat_count | 120 | 客户端超时心跳的最大次数。如果连续等待心跳响应超时的次数 > max_timeout_heartbeat_count,通道将从客户端关闭。 |
7.8 高级网络设置
| 配置项 | 默认值 | 说明 |
|---|---|---|
| transport.max_syn_backlog | 511 | 服务器端 SYN 队列的容量。0 表示使用系统默认值。 |
| transport.recv_file_mode | true | 是否启用接收缓冲文件模式。如果启用,将使用零拷贝从 socket 接收缓冲区并写入文件。注意:需要操作系统支持零拷贝(例如 Linux sendfile/splice)。 |
| transport.network_retries | 3 | 网络通信不稳定时的重试次数。 |
8. 存储与持久化配置
HGKV(HugeGraph Key-Value)存储引擎和值文件的配置。
8.1 HGKV 配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
| hgkv.max_file_size | 2147483648 (2 GB) | 每个 HGKV 文件的最大字节数。 |
| hgkv.max_data_block_size | 65536 (64 KB) | HGKV 文件数据块的最大字节大小。 |
| hgkv.max_merge_files | 10 | 一次合并的最大文件数。 |
| hgkv.temp_file_dir | /tmp/hgkv | 此文件夹用于在文件合并过程中存储临时文件。 |
8.2 值文件配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
| valuefile.max_segment_size | 1073741824 (1 GB) | 值文件每个段的最大字节数。 |
9. BSP 与协调配置
批量同步并行(BSP)协议和 etcd 协调的配置。
| 配置项 | 默认值 | 说明 |
|---|---|---|
| bsp.etcd_endpoints | http://localhost:2379 | etcd 端点；多个地址用逗号分隔。K8s 部署中由 Operator 设置。 |
| bsp.max_super_step | 10 (打包: 2) | 算法的最大超步数。 |
| bsp.register_timeout | 300000 (打包: 100000) | 等待 master 和 worker 注册的最大超时时间(毫秒)。 |
| bsp.wait_workers_timeout | 86400000 (24 小时) | 等待 worker BSP 事件的最大超时时间(毫秒)。 |
| bsp.wait_master_timeout | 86400000 (24 小时) | 等待 master BSP 事件的最大超时时间(毫秒)。 |
| bsp.log_interval | 30000 (30 秒) | 等待 BSP 事件时打印日志的日志间隔(毫秒)。 |
10. 性能调优配置
性能优化的配置。
| 配置项 | 默认值 | 说明 |
|---|---|---|
| allocator.max_vertices_per_thread | 10000 | 每个内存分配器中每个线程处理的最大顶点数。 |
| sort.thread_nums | 4 | 执行内部排序的线程数量。 |
11. 系统管理配置
以下配置由运行系统管理，不应由作业配置覆盖。
以下配置项由 K8s Operator、Driver 或运行时系统自动管理。手动修改将导致集群通信失败或作业调度错误。
| 配置项 | 管理者 | 说明 |
|---|---|---|
| bsp.etcd_endpoints | K8s Operator | 自动设置为 operator 的 etcd 服务地址 |
| transport.server_host | 运行时 | 自动设置为 pod/容器主机名 |
| transport.server_port | 运行时 | 自动分配随机端口 |
| job.namespace | K8s Operator | 自动设置为作业命名空间 |
| job.id | K8s Operator | 自动从 CRD 设置为作业 ID |
| job.workers_count | K8s Operator | 自动从 CRD workerInstances 设置 |
| rpc.server_host | 运行时 | RPC 服务器主机名(系统管理) |
| rpc.server_port | 运行时 | RPC 服务器端口(系统管理) |
| rpc.remote_url | 运行时 | RPC 远程 URL(系统管理) |
为什么禁止修改:
- BSP/RPC 配置:必须与实际部署的 etcd/RPC 服务匹配。手动覆盖会破坏协调。
- 作业配置:必须与 K8s CRD 规范匹配。不匹配会导致 worker 数量错误。
- 传输配置:必须使用实际的 pod 主机名/端口。手动值会阻止 worker 间通信。
K8s Operator 配置选项
注意:选项需要通过环境变量设置进行转换,例如 k8s.internal_etcd_url => INTERNAL_ETCD_URL
| 配置项 | 默认值 | 说明 |
|---|---|---|
| k8s.auto_destroy_pod | true | 作业完成或失败时是否自动销毁所有 pod。 |
| k8s.close_reconciler_timeout | 120 | 关闭 reconciler 的最大超时时间(毫秒)。 |
| k8s.internal_etcd_url | http://127.0.0.1:2379 | operator 系统的内部 etcd URL。 |
| k8s.max_reconcile_retry | 3 | reconcile 的最大重试次数。 |
| k8s.probe_backlog | 50 | 服务健康探针的最大积压。 |
| k8s.probe_port | 9892 | controller 绑定的用于服务健康探针的端口。 |
| k8s.ready_check_internal | 1000 | 检查就绪的时间间隔(毫秒)。 |
| k8s.ready_timeout | 30000 | 检查就绪的最大超时时间(毫秒)。 |
| k8s.reconciler_count | 10 | reconciler 线程的最大数量。 |
| k8s.resync_period | 600000 | 被监视资源进行 reconcile 的最小频率。 |
| k8s.timezone | Asia/Shanghai | computer 作业和 operator 的时区。 |
| k8s.watch_namespace | hugegraph-computer-system | 监视自定义资源的命名空间。使用 ‘*’ 监视所有命名空间。 |
HugeGraph-Computer CRD
| 字段 | 默认值 | 说明 | 必填 |
|---|---|---|---|
| algorithmName | 算法名称。 | true | |
| jobId | 作业 ID。 | true | |
| image | 算法镜像。 | true | |
| computerConf | computer 配置选项的映射。 | true | |
| workerInstances | worker 实例数量,将覆盖 ‘job.workers_count’ 选项。 | true | |
| pullPolicy | Always | 镜像拉取策略,详情请参考:https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy | false |
| pullSecrets | 镜像拉取密钥,详情请参考:https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod | false | |
| masterCpu | master 的 CPU 限制,单位可以是 ’m’ 或无单位,详情请参考:https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu | false | |
| workerCpu | worker 的 CPU 限制,单位可以是 ’m’ 或无单位,详情请参考:https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu | false | |
| masterMemory | master 的内存限制,单位可以是 Ei、Pi、Ti、Gi、Mi、Ki 之一,详情请参考:https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory | false | |
| workerMemory | worker 的内存限制,单位可以是 Ei、Pi、Ti、Gi、Mi、Ki 之一,详情请参考:https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory | false | |
| log4jXml | computer 作业的 log4j.xml 内容。 | false | |
| jarFile | computer 算法的 jar 路径。 | false | |
| remoteJarUri | computer 算法的远程 jar URI,将覆盖算法镜像。 | false | |
| jvmOptions | computer 作业的 Java 启动参数。 | false | |
| envVars | 请参考:https://kubernetes.io/docs/tasks/inject-data-application/define-interdependent-environment-variables/ | false | |
| envFrom | 请参考:https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/ | false | |
| masterCommand | bin/start-computer.sh | master 的运行命令,等同于 Docker 的 ‘Entrypoint’ 字段。 | false |
| masterArgs | ["-r master", “-d k8s”] | master 的运行参数,等同于 Docker 的 ‘Cmd’ 字段。 | false |
| workerCommand | bin/start-computer.sh | worker 的运行命令,等同于 Docker 的 ‘Entrypoint’ 字段。 | false |
| workerArgs | ["-r worker", “-d k8s”] | worker 的运行参数,等同于 Docker 的 ‘Cmd’ 字段。 | false |
| volumes | 请参考:https://kubernetes.io/docs/concepts/storage/volumes/ | false | |
| volumeMounts | 请参考:https://kubernetes.io/docs/concepts/storage/volumes/ | false | |
| secretPaths | k8s-secret 名称和挂载路径的映射。 | false | |
| configMapPaths | k8s-configmap 名称和挂载路径的映射。 | false | |
| podTemplateSpec | 请参考:https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-template-v1/#PodTemplateSpec | false | |
| securityContext | 请参考:https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ | false |
KubeDriver 配置选项
| 配置项 | 默认值 | 说明 |
|---|---|---|
| k8s.build_image_bash_path | 用于构建镜像的命令路径。 | |
| k8s.enable_internal_algorithm | true | 是否启用内部算法。 |
| k8s.framework_image_url | hugegraph/hugegraph-computer:latest | computer 框架的镜像 URL。 |
| k8s.image_repository_password | 登录镜像仓库的密码。 | |
| k8s.image_repository_registry | 登录镜像仓库的地址。 | |
| k8s.image_repository_url | hugegraph/hugegraph-computer | 镜像仓库的 URL。 |
| k8s.image_repository_username | 登录镜像仓库的用户名。 | |
| k8s.internal_algorithm | [pageRank] | 所有内部算法的名称列表。注意:算法名称在这里使用驼峰命名法(例如 pageRank),但算法实现返回下划线命名法(例如 page_rank)。 |
| k8s.internal_algorithm_image_url | hugegraph/hugegraph-computer:latest | 内部算法的镜像 URL。 |
| k8s.jar_file_dir | /cache/jars/ | 算法 jar 将上传到的目录。 |
| k8s.kube_config | ~/.kube/config | k8s 配置文件的路径。 |
| k8s.log4j_xml_path | computer 作业的 log4j.xml 路径。 | |
| k8s.namespace | hugegraph-computer-system | hugegraph-computer 系统的命名空间。 |
| k8s.pull_secret_names | [] | 拉取镜像的 pull-secret 名称。 |
5 - HugeGraph Client
Java 和 Go Client 位于 HugeGraph Toolchain 仓库，Python Client 位于 HugeGraph-AI 仓库。三者的安装方式和 API 不完全相同，请进入对应页面查看。
5.1 - HugeGraph-Java-Client
1 HugeGraph-Client 概述
HugeGraph Java Client 将 Java API 转换为 HugeGraph Server 的 REST 请求，支持管理 Schema 和图数据、执行 Gremlin 及调用 Traverser API。详细接口见 Client API，本文给出 Java 项目的接入示例。
其他语言可使用 Go Client 或 HugeGraph-AI 仓库中的 Python Client。
2 环境要求
- JDK 11（当前 CI 使用版本；源码目标版本为 Java 8）
- Maven 3.6+
3 使用流程
使用 HugeGraph-Client 的基本步骤如下：
- 新建Eclipse/ IDEA Maven 项目；
- 在 pom 文件中添加 HugeGraph-Client 依赖；
- 创建类，调用 HugeGraph-Client 接口；
详细使用过程见下节完整示例。
4 完整示例
4.1 新建 Maven 工程
可以选择 Eclipse 或者 Intellij Idea 创建工程：
4.2 添加 hugegraph-client 依赖
添加 hugegraph-client 依赖
Client 与 Server 的开发版本可能不同。升级前应按对应发布说明核对兼容性。
4.3 Example
4.3.1 SingleExample
4.3.2 BatchExample
4.4 运行 Example
运行 Example 之前需要启动 Server, 启动过程见HugeGraph-Server Quick Start
4.5 详细 API 说明
5.2 - HugeGraph Python 客户端快速入门
hugegraph-python-client 是 HugeGraph 的 Python SDK，可管理 Schema、读写图数据并执行 Gremlin 查询。HugeGraph-LLM 和 HugeGraph-ML 也使用这个客户端。
环境要求
- Python 3.9 或更高版本
- 可访问的 HugeGraph Server
uv（推荐）或pip
安装
PyPI 上的包名目前是 hugegraph-python：
如需使用仓库中的最新代码，请从 HugeGraph-AI 仓库根目录同步 workspace：
连接并写入数据
如果 HugeGraph 没有启用 GraphSpace，可以省略 graphspace。启用后请传入实际空间名；默认空间通常是 DEFAULT。
常用操作
查询 Schema
更新和删除图数据
图接口直接接收对象属性字典：
执行 Gremlin
接口参数会随 HugeGraph REST API 版本变化。遇到不兼容时，先核对当前 Server 的 REST API 文档与客户端测试用例。
开发检查
在 HugeGraph-AI 仓库根目录运行格式与静态检查：
源码与测试位于 hugegraph-python-client/src/pyhugegraph/ 和 hugegraph-python-client/src/tests/。
5.3 - HugeGraph Go 客户端快速入门
HugeGraph Go Client 是 Toolchain 仓库中的 Go SDK，目前提供版本查询、Schema、顶点、边和 Gremlin API。
该模块仍在开发中。接口范围以
hugegraph-client-go/api/v1下的源码为准。
环境要求
- Go 1.19 或更高版本
- 可访问的 HugeGraph Server，默认示例地址为
http://127.0.0.1:8080
安装
在 Go module 项目中执行：
初始化客户端
NewCommonClient 要求 Host 是 IP 地址；未启用认证时，用户名和密码留空。当前 Server 的图资源路径包含图空间，默认填写 DEFAULT。将 GraphSpace 留空只适用于仍使用 /graphs/{graph} 路径的旧版 Server。
Version() 返回的 Versions 包含 HugeGraph Server、Core、Gremlin 和 REST API 版本。若使用源码提供的 NewDefaultCommonClient()，默认连接 127.0.0.1:8080 下的 hugegraph 图，并使用 admin/pa 认证；生产代码通常应显式传入配置。
已实现的入口
CommonClient 当前公开以下入口：
| 入口 | 用途 |
|---|---|
Version() | 查询服务端版本 |
Schema() | 查询完整 Schema |
Propertykey | 管理 PropertyKey |
VertexLabel | 管理 VertexLabel |
EdgeLabel | 管理 EdgeLabel |
Vertex | 创建、批量创建和更新顶点属性 |
Gremlin | 通过 GET 或 POST 执行 Gremlin |
完整调用方式可参考各 API 目录中的测试，例如 version_test.go 和 vertexlabel_test.go。