HugeGraph ToolChain

• 1: 使用 Hubble 实现图可视化：单机快速上手
• 2: 图可视化
  • 2.1: 使用 Hubble 管理 HStore 分布式集群
• 3: HugeGraph-Loader 快速上手
• 4: 图导入
  • 4.1: 使用 SeaTunnel Sink 导入图数据
• 5: Tools 快速上手
• 6: 图导出/迁移
  • 6.1: 使用 SeaTunnel Source 导出与迁移图数据
• 7: HugeGraph-Spark-Connector 快速上手

1 - 使用 Hubble 实现图可视化：单机快速上手

Hubble 是 HugeGraph 的 Web 管理与图可视化界面。你可以在同一个工作台中管理图的 Schema、导入数据、执行查询， 并在图、表格和 JSON 视图之间切换。本文用 单机 RocksDB Server + Hubble 走通这些操作，不需要 PD 或 Store。

如果使用 HStore，请先阅读本文的通用操作，再看 HStore 分布式补充。 本文以 Toolchain master（当前为 1.8.0）为准；Docker latest 是可变标签，使用时应核对实际版本。

启动单机组合

直接使用主仓库 docker/docker-compose.yml， 无需另外编写一份 Compose。文件已经组合了 RocksDB Server 与 Hubble，并配置网络、健康检查和数据卷； 部署细节见同目录的 README。

1git clone --branch master --single-branch --depth 1 https://github.com/apache/hugegraph.git
2cd hugegraph/docker

如果已有主仓库，直接进入它的 docker/ 目录。Compose 挂载该目录下的 conf/hubble/standalone.properties， 其中 pd.enabled=false、server.direct_url=http://server:8080：两个服务在同一 Docker 网络中通信，不需要填写每图 Server 地址。 不要只下载 YAML 后从其他目录启动，否则相对配置文件路径可能不存在。

Hubble 默认只在宿主机回环地址开放 8088；Server 默认发布 8080。仅本机试用时，将 Compose 中 Server 的 ports 改为 127.0.0.1:8080:8080，避免对其他机器开放匿名接口。

为本次试用选一个未被使用的项目名，后续命令在同一终端沿用这些变量；另开终端时恢复本次项目名。

1export HUGEGRAPH_VERSION=latest
2export HUBBLE_IMAGE=hugegraph/hubble:latest
3export HUBBLE_DEMO_PROJECT="hubble-demo-$(date +%Y%m%d-%H%M%S)"
4docker compose ls
5docker compose -p "$HUBBLE_DEMO_PROJECT" -f docker-compose.yml pull
6docker compose -p "$HUBBLE_DEMO_PROJECT" -f docker-compose.yml up -d --wait
7docker compose -p "$HUBBLE_DEMO_PROJECT" -f docker-compose.yml ps
8curl -fsS http://127.0.0.1:8080/versions

服务健康后，打开 http://127.0.0.1:8088。全新目录未配置 HUGEGRAPH_ADMIN_PASSWORD 时，Server 允许匿名访问， Hubble 直接进入首页。需要认证时，按 Docker README 配置 .env 中的管理员密码与 JWT 密钥，使用 Server 账号登录； Hubble 没有独立账号库。个人中心与账号管理只在相应认证和权限条件下显示，不要覆盖已有 .env。

latest 便于体验当前功能，正式部署应固定镜像版本或 digest。镜像是便捷分发物，正式发布包见 下载页。 算法与账号配图使用 Toolchain 1.8.0 构建的 Hubble 与 Server 1.7.0。Hubble 的 /about 当前返回静态值 3.0.0， 不能据此判断构建版本；此组合只说明这些配图的运行环境，不保证 latest 始终对应这些版本。界面入口仍取决于 Server 提供的能力。 Compose 的 server-data 和 hubble-data 分别保存图数据与 Hubble 元数据；更多持久化与生产配置见 Server 部署指南。

首页：找到当前任务的入口

首页按“图概览 → 图导入 → 图查询”组织工作入口，适合第一次使用时了解整体流程。 左侧导航可随时返回各栏目；顶部的图选择器决定查询、Schema 和异步任务的操作对象，切换页面后也要留意当前图。 单机模式只有 DEFAULT 图空间，不需要额外配置 PD。

界面速览

先通过画廊认识图概览、Schema 和查询三个工作区。点击截图可放大；下文各操作章节保留大图，便于对照具体步骤。

• 

  图概览：选择图并查看示例数据

• 

  Schema：查看顶点类型、主键与 ID 策略

• 

  图查询：执行 Gremlin 并探索图结果

图概览与图详情：先认识一张图

从【图概览】选择默认图 hugegraph。图概览提供图的入口与操作菜单；进入详情后， 可以查看 Schema 和数据统计，并跳转到建模、数据准备或查询。统计提供整体规模信息，导入或修改数据后可重新更新。

在图的【更多操作】菜单中加载【人物与软件 Demo 图】。示例会补齐对应 Schema 和缺失的数据，不清空已有图； 初次体验请使用空图，避免同名 Schema 与示例定义冲突。本文后续都使用这张图，探索人物和软件之间的关系。

新建图入口取决于 Server 的建图能力。表单填写图名称、可选别名及模板或示例数据，不填写每图 Server 主机与账号； Server 连接统一来自 Hubble 配置。用户自建 Schema 模板属于 PD 模式，见 分布式补充。

Schema 建模：定义数据的形状

Schema 决定哪些属性和关系可以写入图，以及顶点 ID 和查询索引如何生成。 从【元数据配置】进入，列表视图方便维护定义，图视图帮助理解顶点与边的结构。

在人物与软件示例中，person 通过 name 主键生成 ID，age 与 city 可以为空； software 使用自定义数值 ID，created 连接人物与软件。它们对应 Loader 完整示例。

建立自己的模型时，按“属性 → 顶点类型 → 边类型 → 索引”准备。关联属性和索引信息可以帮助检查类型的依赖关系。 删除类型和创建、重建索引可能提交后台任务；操作被接受后，还需到【异步任务】确认最终状态。

GQL 工作台：查询与探索人物关系

进入【GQL 图遍历】，确认当前图为 hugegraph。工作台将查询编辑器与结果区放在一起， 可选择立即执行或异步执行，收藏常用语句，也可以从执行记录加载查询。 先在 Gremlin 编辑器执行人物属性查询：

1g.V().hasLabel('person').valueMap()

这条查询适合在表格或 JSON 视图核对属性。要观察人物与软件的关系，执行：

1g.V().hasLabel('person').outE('created').inV().path()

图结果支持 2D / 3D 展示。点击顶点或边查看 ID、类型和属性，双击顶点展开邻居； 布局、样式和筛选工具帮助突出重点，导出功能便于分享结果。【新增】用于创建元素，有权限时也可以编辑已有数据。 调整布局、颜色或显示范围只改变画布；新增、编辑和 Gremlin 写入才会改变 Server 中的数据。

Ctrl / Command + Enter 执行查询。立即执行适合小规模探索；长查询可交给后台任务，避免一次返回整张大图。 Cypher 页签只在 Server 支持时提供。Text2GQL 当前是界面预览，未连接模型或查询服务，不能直接生成可执行查询。

内置图算法：用表单探索关系

不想从头编写遍历语句时，可以进入【内置图算法】，搜索算法并填写参数。 邻居探索用于回答“这个点附近有什么”，路径算法用于寻找两个点的连接，相似度和排序算法用于比较或筛选顶点。 从一个已知顶点 ID 开始，先限定方向、边类型、深度与返回规模，再观察结果，会比直接运行大范围计算更容易理解。

算法表单提供参数说明及文档入口；常用参数可以在页面间往返时恢复。 运行结果按算法显示为图或相应的结果面板；需要理解具体定义和参数时，使用算法标题旁的说明与文档链接。 表单聚焦时也可用 Ctrl / Command + Enter 运行当前算法。

OLAP 批量算法需要 Computer 或 Vermeer 等外部计算环境。本例的两个容器用于在线图操作，不包含这些计算服务。

例如选择 K-neighbor（GET），设置 source=1:marko、max_depth=1、limit=20， 参数校验通过后点击卡片右侧运行按钮，或在参数表单内使用快捷键，即可观察一跳邻居。

异步任务：确认后台操作的最终结果

【异步任务】集中显示当前图的后台任务，包括异步查询及部分 Schema、索引操作。 可以按任务类型和状态筛选，查看任务 ID、创建时间与执行状态；成功查询可打开结果，失败任务可展开错误信息。 已结束的任务可按界面提供的操作删除记录，任务列表与导入任务的执行历史是两个不同入口。

例如把 g.V().count() 以异步方式提交后，先在列表确认成功，再查看返回的数量。 “提交成功”只表示请求被接受，不表示计算或索引已完成。排查失败时，结合任务错误和 Server 日志定位原因。

数据源管理：把原始数据准备好

数据源负责“从哪里读、怎样解析”，可以被导入任务引用。Hubble 支持 FILE、HDFS、JDBC 和 Kafka； 不同来源需要对应的路径、连接或订阅配置。FILE 最适合先体验：上传文件后，配置格式、分隔符、编码和表头， 检查读取的列名，再进入映射。上传限制和允许的扩展名由 Hubble 配置决定。

为人物示例保存一个 UTF-8 文件 people.csv：

1name,age,city
2docs_alice,28,Beijing
3docs_bob,32,Shanghai

创建 FILE 数据源并上传它，选择 CSV（逗号分隔、默认 UTF-8），列名为 name,age,city。 表头、分隔符和编码属于数据源配置，不在后面的映射步骤设置；源字段应与文件内容一致。

数据导入：从字段映射到可查询的图

【数据导入】把数据源中的行转换为顶点和边。任务创建采用四段配置，先明确目标，再选择字段和映射，最后决定执行时机。 沿用上面的数据源，在 DEFAULT / hugegraph 中创建人物导入任务：

person 使用 PRIMARY_KEY，不设置独立 ID 列。自定义 ID 策略需要指定 ID 列； AUTOMATIC 由 Server 生成 ID，PRIMARY_KEY 根据映射的主键属性生成 ID。边映射还需指定起点、终点字段并匹配对应顶点的 ID 规则。

任务列表用于管理配置和执行入口，详情中的执行历史用于查看每次实例的状态、导入量与错误。 Hubble 还提供周期调度和 Kafka 实时执行，调度方式需与数据源类型匹配。 完成后返回 GQL 工作台验证：

1g.V().hasLabel('person').has('name', within('docs_alice', 'docs_bob')).valueMap()

结果应包含两条新人物记录。导入量统计不应直接当作新增顶点数；重跑可能更新已有元素，表头处理也会影响读取统计。 失败时先检查源字段、数值类型、可空属性及目标 Schema。Hubble 导入适合小规模体验， 大批量正式导入请使用 HugeGraph Loader。

个人中心与账号权限

Hubble 使用 Server 的认证和账号，没有独立用户库。匿名访问时不显示【个人中心】与【账号管理】； 开启认证后，个人中心展示当前账号资料与权限信息，可修改自己的密码。昵称等资料编辑依赖 Server 对个人资料接口的支持。 修改密码后会退出当前会话，需要重新登录。

单机账号管理

单机模式由管理员管理账号，可创建、查看、编辑或删除账号，并支持批量创建。 通过 Hubble 新建的普通单机账号会获得覆盖所有图的读、写、删除和执行权限，不能把它当作只读账号或单图隔离账号。 需要更细的资源权限时，应按 Server 认证与授权配置，而不是依赖空间预设。

PD 模式的空间权限

连接支持默认角色接口的 Server 后，账号与空间访问可以分别管理。管理员管理全局账号， 空间管理员只管理已授权空间的成员；普通成员不会获得账号管理或运维入口。 以下四种预设属于 PD 模式，不表示旧版本或单机 Server 都提供同样的权限编辑能力：

同一账号在不同空间可以有不同权限。成员管理先选择空间，再添加已有账号或调整权限； 把已有自定义权限替换为预设前，先核对需要保留的授权，避免把复杂权限误认为单一预设。 权限变更后刷新权限上下文或重新登录，确认菜单和目标空间已更新；最终请求仍由 Server 校验。 旧 Server 未提供相应接口时，页面按能力隐藏或禁用操作，不应只凭按钮是否可见推断资源权限。 更完整的空间管理见 分布式补充。

系统运维：检查单机 Server

单机模式的【系统运维】提供【节点信息】，只显示 Server，不显示 PD / Store 节点或集群概览。 节点列表可搜索、筛选健康状态并进入详情；详情用于查看可用的版本、系统、JVM、Server 后端等指标。 指标缺失或标记过期时，应结合采集状态与最近成功时间判断，不能把空值当作零或健康。

匿名模式可以查看运维信息；开启认证后，运维入口仅对有运维权限的管理员显示。 此处用于观测和排查，不是启动、停止或扩缩容控制台。PD 模式的集群概览与节点层级见分布式补充。

快捷键与画布操作

顶部的快捷键帮助入口随时可查看按键说明。以下快捷键有不同的作用范围，输入框中不会触发全局 ? 帮助。

排查连接与结果问题

查询显示规模受配置影响。gremlin.suffix_limit 默认 250，用于对适用的 Gremlin 查询追加 .limit(N)， 不是所有查询的硬上限；gremlin.vertex_degree_limit（100）与 gremlin.edges_total_limit（500）限制展开规模。 FILE 上传默认允许 csv,txt，单文件 1 GB、总量 10 GB；需要覆盖时修改 upload_file.* 配置。

停止试用环境或从源码构建

不再需要示例时，在主仓库的 docker/ 目录执行：

1docker compose -p "${HUBBLE_DEMO_PROJECT:?}" -f docker-compose.yml down --volumes

这会删除该项目的容器、网络、命名卷与匿名卷，示例图和 Hubble 导入任务也会丢失。 若想保留数据，下线时省略 --volumes，以后用同一项目名启动。

需要与 master 精确一致的产物时，使用 JDK 11 和 Maven 从 Toolchain 构建。 Maven 插件会安装所需的 Node/Yarn，无需预先安装；以下命令不执行测试：

1git clone --branch master --single-branch https://github.com/apache/hugegraph-toolchain.git
2cd hugegraph-toolchain
3mvn install -pl hugegraph-client,hugegraph-loader -am -Dmaven.javadoc.skip=true -DskipTests -ntp
4cd hugegraph-hubble
5mvn package -Dmaven.javadoc.skip=true -DskipTests -ntp
6cd apache-hugegraph-hubble-*
7# 编辑 conf/hugegraph-hubble.properties，设置正确的 Server URL
8bin/start-hubble.sh

打包配置默认绑定本机 localhost:8088。bin/stop-hubble.sh 会先请求正常停机，超时后才强制终止。 需要开发与测试说明时，参考 Toolchain 本地测试指南。

2 - 图可视化

Hubble 为 HugeGraph 提供图数据、Schema、查询和导入的 Web 界面。先从不依赖 PD 的单机组合入手， 再按需要了解分布式集群的差异。

• Hubble 基础与单机 RocksDB：启动、示例图、建模、导入与查询。
• Hubble 与 HStore 分布式集群：PD 发现、图空间与集群运维。

2.1 - 使用 Hubble 管理 HStore 分布式集群

本篇补充 HStore + PD 部署与单机 RocksDB 的差异。建模、导入和查询的通用操作见 Hubble 基础与单机指南。 内容以 Toolchain master 为准。

主仓库的 docker/docker-compose-hstore.yml 已提供 PD、Store、Server 与 Hubble 的组合。按同目录 Docker README 准备 .env 和生成的 Hubble 本地配置，再从 docker/ 目录启动；不要另维护一份部署 YAML。 下文配置用于解释连接差异，不能替代 README 中 PD 凭据及服务就绪的要求。 图中使用 Toolchain 1.8.0 构建的 Hubble 与 Server、PD、Store 1.7.0。Hubble 的 /about 当前返回静态值 3.0.0， 不能据此判断构建版本；此组合只对应本篇配图的运行环境，latest 标签会变化。不同版本可提供的指标和权限接口有所区别。

连接分布式集群

Hubble 仍通过 Server 的图 API 管理数据。区别在于，分布式模式通过 PD 发现 Server， 同时从 PD 和 Store 获取集群信息；Hubble 不直接读写 Store 中的图数据。

使用官方 Compose 时，先按 Docker README 在主仓库的 docker/ 目录准备 .env，再生成它挂载的 Hubble 配置：

1set -a
2. ./.env
3set +a
4./set-hubble-pd-password.sh hstore

脚本读取 .env 中已载入的 HG_PD_AUTH_SECRET_KEY，将 PD 运维密码写入宿主机的 docker/conf/hubble/hstore.local.properties。 如需调整连接地址或运维配置，编辑这个生成文件，并保留生成的 operations.pd.password，使其与 PD 使用的密钥一致。 不要覆盖为跟踪的 .example 模板。Compose 将它只读挂载到容器的 /hubble/conf/hugegraph-hubble.properties， 不要进入容器修改。生成文件和 .env 都不应提交；以后重新运行脚本会覆盖生成文件，需要重新应用自定义配置。

在同一 docker/ 目录启动组合，并确认 Server 已注册、Store 已就绪：

1docker compose -f docker-compose-hstore.yml up -d --wait

若分别部署服务，参照 PD 部署指南 和 HStore 部署指南；源码或二进制包启动的 Hubble 则编辑其 conf/hugegraph-hubble.properties。以下连接项与官方最小拓扑一致，其他部署请使用 Hubble 后端实际可达的地址：

1pd.enabled=true
2cluster=hg
3pd.peers=pd:8686
4pd.server=pd:8620

不要把 8686 和 8620 混用，也不要在跨容器连接时保留 127.0.0.1。 随包文件显式设置 pd.enabled=false，而该键缺失时 Java 默认值是 true，因此两种部署都应显式设置它。 源码或二进制包部署在修改配置后重启 Hubble。Compose 部署在修改或重新生成宿主机配置后，从 docker/ 目录重建 Hubble 容器， 使只读挂载重新载入文件（沿用启动时的项目名及所有 -f 参数）：

1docker compose -f docker-compose-hstore.yml up -d --force-recreate hubble

页面无需逐图填写 Server 主机和端口。

用图空间组织图与权限

GraphSpace（图空间）将图、Schema 模板和访问权限组织在同一个范围内。例如，分别为业务团队创建 sales 与 research， 让各团队只看到并操作自己的图。进入图空间后，图的建模、导入和查询仍沿用基础指南的流程。

创建与调整图空间

开启 Server 认证时，创建、编辑和删除图空间要求超级管理员权限。创建时先填写全局唯一的 GraphSpace 名称、 可选的显示别名及最大图数；例如用 research 作 API 标识，用“研究图谱”作显示名。GraphSpace 名称创建后不可修改， 别名和描述可随后调整，别名不参与 URL 或权限匹配。图空间管理员从已有账号中选择。

“高级部署与资源限制”包含图查询/写入服务、异步计算任务的 CPU 与内存上限，以及存储容量限制。 这些值用于部署和配额场景，不是当前资源用量，也不代表提交表单后会立即扩容 Docker 容器。 默认最大图数为 100；图服务与计算任务分别为 64 核、128 GB，存储上限为 1000000 GB。 普通容器试用可先保留默认值；Kubernetes 命名空间、Operator 和算法镜像仅在对应部署或计算场景中填写。

选择图空间后，再进入其中的图。切换空间时应重新确认当前图，尤其是不同空间中存在同名图时。 列表只显示账号可访问的空间；看不到预期空间时，先检查成员权限，不要反复新建图。

复用 Schema 模板

用户 Schema 模板仅适用于 PD 模式，按图空间持久化保存 Groovy Schema。 当一组业务图需要同样的顶点类型、边类型和索引时，可以先保存模板，再在创建图时选择它，减少重复建模。 例如 research 中的用户模板用于该空间后续创建的图；切换到另一个空间后，应重新选择该空间的模板。

用户模板与主篇的内置示例模板不同：内置模板用于快速体验预设模型，用户模板用于保存自己的模型并长期复用。 模板本身不等于导入数据；是否加载示例数据是创建图时的另一个选择。 开启 Server 认证时，创建用户模板需要所在空间的写权限，更新或删除还要求模板所有者或相应管理权限。 匿名模式不进行按用户的权限与模板所有者检查。 单机模式不提供用户模板管理。

给用户分配图空间权限

账号创建、登录和个人资料管理见基础指南； 分布式模式额外提供“管理 GraphSpace 成员”，在已有账号与指定空间之间分配权限。 支持权限预设的 Server 提供以下常用选择：

同一账号可在不同空间拥有不同权限，例如对 research 读写、对 sales 只读。 账号与空间成员分开管理，移除成员不会删除全局账号。创建账号后可以立即继续分配空间权限；调整已有成员时，确认当前空间及预设，保留其他空间仍需要的权限。 仅启用 pd.enabled 不会授予权限，旧 Server 的自定义角色也不能直接当作这些预设处理。 认证配置见 Server 认证与授权。

从集群概览定位异常

集群概览用一张拓扑展示 Server → PD → Store，可切换节点列表按类型、状态或名称筛选。 概览中的 PD Leader、在线 Store 数、图数、分区数、副本数和数据量，帮助判断当前连接的规模及哪些节点需要关注。 分区和副本描述数据分布；数据量是采集到的用量，不是图空间配置的存储上限。

先看集群和来源状态，再进入异常节点：UP 表示本次采集的来源正常；DEGRADED 表示集群或部分来源异常； DOWN 表示相应探测未成功。拓扑可用而指标部分缺失时，仍可能正常查询图。 页面会区分不支持、不可用、数据过期和采集失败，并显示采集时间；空值不是零，历史值也不等于当前状态。

节点详情读什么

PD Leader 与 Store 的 Leader 分区不是同一概念：前者协调集群元数据，后者负责相应数据分区的 Raft 组。 Hubble 展示上游提供的观测值，不代替完整的 Raft 副本一致性检查；各版本可用的指标不同。

开启 Server 认证时，集群运维读取要求超级管理员（ADMIN 级别），空间管理员和普通成员不会因此获得集群读取权限。 部署时使用容器隔离、可信 HTTPS 入口、Server 认证与网络白名单，避免直接公开 Hubble 和组件端口。

配置运维访问

PD/Store 的运维凭据由 Hubble 后端使用，与浏览器登录 Server 的账号分开。 Compose 部署修改上文生成的宿主机 docker/conf/hubble/hstore.local.properties；其他部署修改 Hubble 包内配置文件。 其中 PD 密码由脚本生成并与 .env 中的密钥保持一致，Store 启用认证时再配置对应服务账号。不要把密码写进文档、截图或提交的配置：

例如容器中的 Store 上报 store:8520，将白名单配置为：

1operations.store.allowed_targets=[http://store:8520]

多节点时列出每个允许访问的来源。每项必须是带显式端口的 http 或 https origin，不能带路径、凭据或通配符， 并且应与 PD 返回的 Store 指标目标一致。仅在白名单里添加地址不会建立节点发现信息。

若拓扑可见但指标不完整，依次检查 Hubble 后端到 PD REST 的连通性与认证、PD 返回的 Store REST/指标目标， 以及目标是否与白名单一致。概览的部分可用状态表示某些来源尚未成功采集，不等同于所有图 API 都不可用。

3 - HugeGraph-Loader 快速上手

本文以 Toolchain master（当前版本为 1.8.0）为准。发布版和 Docker latest 可能与源码不同；使用时请核对版本，未发布的版本请按下文从源码构建。

1 HugeGraph-Loader 概述

HugeGraph-Loader 是 HugeGraph 的数据导入组件，能够将多种数据源的数据转化为图的顶点和边并批量导入到图数据库中。

目前支持的数据源包括：

• 本地磁盘文件或目录，支持 TEXT、CSV 和 JSON 格式的文件，支持压缩文件
• HDFS 文件或目录，支持压缩文件
• 主流关系型数据库，如 MySQL、PostgreSQL、Oracle、SQL Server
• Kafka topic
• 已有的 HugeGraph 图，用于把数据从一个图复制到另一个图

本地磁盘文件和 HDFS 文件支持断点续传。

后面会具体说明。

注意：使用 HugeGraph-Loader 需要依赖 HugeGraph Server 服务，下载和启动 Server 请参考 HugeGraph-Server 快速上手

测试指南：如需在本地运行 Loader 测试，请参考 工具链本地测试指南

2 获取 HugeGraph-Loader

可以通过以下三种方式获取 HugeGraph-Loader：

• 使用 Docker 镜像 (便于测试)
• 下载已编译的压缩包
• 克隆源码编译安装

2.1 使用 Docker 镜像 (便于测试)

我们可以使用 docker run -itd --name loader hugegraph/loader:latest 部署 loader 服务。对于需要加载的数据，则可以通过挂载 -v /path/to/data/file:/loader/file 或者 docker cp 的方式将文件复制到 loader 容器内部。

或者使用 docker-compose 启动 loader, 启动命令为 docker-compose up -d, 样例的 docker-compose.yml 如下所示：

以下组合用于本地匿名试用，Server API 只发布到本机。

 1version: '3'
 2
 3services:
 4  server:
 5    image: hugegraph/hugegraph:latest
 6    container_name: server
 7    ports:
 8      - 127.0.0.1:8080:8080
 9
10  loader:
11    image: hugegraph/loader:latest
12    container_name: loader
13    # mount your own data here
14    # volumes:
15      # - /path/to/data/file:/loader/file

具体的数据导入流程可以参考 4.5 使用 docker 导入

注意：

1. hugegraph-loader 的 docker 镜像是一个便捷版本，用于快速启动 loader，并不是官方发布物料包方式。你可以从 ASF Release Distribution Policy 中得到更多细节。

2. 生产环境应固定已发布的版本标签或镜像 digest。latest 是可变标签，不能据此判断其与 master 一致。

2.2 下载已编译的压缩包

从 下载页面 选择已发布的 Toolchain 压缩包并解压。 发布包不一定包含 master 的全部功能；需要本文对应实现时，使用下一节的源码构建方式。

2.3 克隆源码编译安装

克隆 master 分支：

1git clone --branch master --single-branch https://github.com/apache/hugegraph-toolchain.git

编译生成 tar 包：

1cd hugegraph-toolchain
2mvn clean package -pl hugegraph-loader -am -DskipTests -ntp

如需读取 Oracle 数据，按所用 Oracle/JDK 版本准备兼容的 JDBC 驱动 JAR，并放入解压后 Loader 的 lib/ 目录。 启动脚本会加载该目录中的 JAR；仅将驱动安装到 Maven 本地仓库并不会让运行中的 Loader 找到它。

3 使用流程

使用 HugeGraph-Loader 的基本流程分为以下几步：

• 编写图模型
• 准备数据文件
• 编写输入源映射文件
• 执行命令导入

3.1 编写图模型

这一步是建模的过程，用户需要对自己已有的数据和想要创建的图模型有一个清晰的构想，然后编写 schema 建立图模型。

比如想创建一个拥有两类顶点及两类边的图，顶点是"人"和"软件"，边是"人认识人"和"人创造软件"，并且这些顶点和边都带有一些属性，比如顶点"人"有：“姓名”、“年龄"等属性， “软件"有：“名字”、“售卖价格"等属性；边"认识"有：“日期"属性等。

示例图模型

在设计好了图模型之后，我们可以用groovy编写出schema的定义，并保存至文件中，这里命名为schema.groovy。

 1// 创建一些属性
 2schema.propertyKey("name").asText().ifNotExist().create();
 3schema.propertyKey("age").asInt().ifNotExist().create();
 4schema.propertyKey("city").asText().ifNotExist().create();
 5schema.propertyKey("date").asText().ifNotExist().create();
 6schema.propertyKey("price").asDouble().ifNotExist().create();
 7
 8// 创建 person 顶点类型，其拥有三个属性：name, age, city，主键是 name
 9schema.vertexLabel("person").properties("name", "age", "city").primaryKeys("name").ifNotExist().create();
10// 创建 software 顶点类型，其拥有两个属性：name, price，主键是 name
11schema.vertexLabel("software").properties("name", "price").primaryKeys("name").ifNotExist().create();
12
13// 创建 knows 边类型，这类边是从 person 指向 person 的
14schema.edgeLabel("knows").sourceLabel("person").targetLabel("person").properties("date").ifNotExist().create();
15// 创建 created 边类型，这类边是从 person 指向 software 的
16schema.edgeLabel("created").sourceLabel("person").targetLabel("software").ifNotExist().create();

关于 schema 的详细说明请参考 HugeGraph Java Client 中对应部分。

3.2 准备数据

目前 HugeGraph-Loader 支持的数据源包括：

• 本地磁盘文件或目录
• HDFS 文件或目录
• 部分关系型数据库
• Kafka topic
• 已有的 HugeGraph 图

3.2.1 数据源结构

3.2.1.1 本地磁盘文件或目录

用户可以指定本地磁盘文件作为数据源，如果数据分散在多个文件中，也支持以某个目录作为数据源，但暂时不支持以多个目录作为数据源。

比如：我的数据分散在多个文件中，part-0、part-1 … part-n，要想执行导入，必须保证它们是放在一个目录下的。然后在 loader 的映射文件中，将path指定为该目录即可。

支持的文件格式包括：

• TEXT
• CSV
• JSON

TEXT 是自定义分隔符的文本文件，第一行通常是标题，记录了每一列的名称，也允许没有标题行（在映射文件中指定）。其余的每行代表一条记录，会被转化为一个顶点/边；行的每一列对应一个字段，会被转化为顶点/边的 id、label 或属性；

示例如下：

1id|name|lang|price|ISBN
21|lop|java|328|ISBN978-7-107-18618-5
32|ripple|java|199|ISBN978-7-100-13678-5

CSV 是分隔符为逗号,的 TEXT 文件，当列值本身包含逗号时，该列值需要用双引号包起来，如：

1marko,29,Beijing
2"li,nary",26,"Wu,han"

JSON 文件要求每一行都是一个 JSON 串，且每行的格式需保持一致。

1{"source_name": "marko", "target_name": "vadas", "date": "20160110", "weight": 0.5}
2{"source_name": "marko", "target_name": "josh", "date": "20130220", "weight": 1.0}

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

1// person 表结构
2id | name | age | city 

1// software 表结构
2id | name | lang | price

1// created 表结构
2id | p_id | s_id | date

如果在建模（schema）时指定 person 或 software 的 id 策略是 PRIMARY_KEY，选择以 name 作为 primary keys（注意：这是 hugegraph 中 vertexlabel 的概念），在导入边数据时，由于需要拼接出源顶点和目标顶点的 id，必须拿着 p_id/s_id 去 person/software 表中查到对应的 name，这种需要做额外查询的表结构的情况，loader 暂时是不支持的。这时可以采用以下两种方式替代：

1. 仍然指定 person 和 software 的 id 策略为 PRIMARY_KEY，但是以 person 表和 software 表的 id 列作为顶点的主键属性，这样导入边时直接使用 p_id 和 s_id 和顶点的 label 拼接就能生成 id 了；
2. 指定 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）

1Tom,48,Beijing
2Jerry,36,Shanghai

• software 顶点数据（数据本身包含 header）

1name,price
2Photoshop,999
3Office,388

3.2.2.2 边数据

边数据文件由一行一行的数据组成，一般每一行作为一条边，其中有部分列会作为源顶点和目标顶点的 id，其他列作为边属性。下面以 JSON 格式作为示例进行说明。

• knows 边数据

1{"source_name": "Tom", "target_name": "Jerry", "date": "2008-12-12"}

• created 边数据

1{"source_name": "Tom", "target_name": "Photoshop"}
2{"source_name": "Tom", "target_name": "Office"}
3{"source_name": "Jerry", "target_name": "Office"}

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{
 2  "version": "2.0",
 3  "structs": [
 4    {
 5      "id": "1",
 6      "input": {
 7      },
 8      "vertices": [
 9        {},
10        {}
11      ],
12      "edges": [
13        {},
14        {}
15      ]
16    }
17  ]
18}

这里直接给出两个版本的映射文件（描述了上面图模型和数据文件）

  1{
  2  "version": "2.0",
  3  "structs": [
  4    {
  5      "id": "1",
  6      "skip": false,
  7      "input": {
  8        "type": "FILE",
  9        "path": "vertex_person.csv",
 10        "file_filter": {
 11          "extensions": [
 12            "*"
 13          ]
 14        },
 15        "format": "CSV",
 16        "delimiter": ",",
 17        "date_format": "yyyy-MM-dd HH:mm:ss",
 18        "time_zone": "GMT+8",
 19        "skipped_line": {
 20          "regex": "(^#|^//).*|"
 21        },
 22        "compression": "NONE",
 23        "header": [
 24          "name",
 25          "age",
 26          "city"
 27        ],
 28        "charset": "UTF-8",
 29        "list_format": {
 30          "start_symbol": "[",
 31          "elem_delimiter": "|",
 32          "end_symbol": "]"
 33        }
 34      },
 35      "vertices": [
 36        {
 37          "label": "person",
 38          "skip": false,
 39          "id": null,
 40          "unfold": false,
 41          "field_mapping": {},
 42          "value_mapping": {},
 43          "selected": [],
 44          "ignored": [],
 45          "null_values": [
 46            ""
 47          ],
 48          "update_strategies": {}
 49        }
 50      ],
 51      "edges": []
 52    },
 53    {
 54      "id": "2",
 55      "skip": false,
 56      "input": {
 57        "type": "FILE",
 58        "path": "vertex_software.csv",
 59        "file_filter": {
 60          "extensions": [
 61            "*"
 62          ]
 63        },
 64        "format": "CSV",
 65        "delimiter": ",",
 66        "date_format": "yyyy-MM-dd HH:mm:ss",
 67        "time_zone": "GMT+8",
 68        "skipped_line": {
 69          "regex": "(^#|^//).*|"
 70        },
 71        "compression": "NONE",
 72        "header": null,
 73        "charset": "UTF-8",
 74        "list_format": {
 75          "start_symbol": "",
 76          "elem_delimiter": ",",
 77          "end_symbol": ""
 78        }
 79      },
 80      "vertices": [
 81        {
 82          "label": "software",
 83          "skip": false,
 84          "id": null,
 85          "unfold": false,
 86          "field_mapping": {},
 87          "value_mapping": {},
 88          "selected": [],
 89          "ignored": [],
 90          "null_values": [
 91            ""
 92          ],
 93          "update_strategies": {}
 94        }
 95      ],
 96      "edges": []
 97    },
 98    {
 99      "id": "3",
100      "skip": false,
101      "input": {
102        "type": "FILE",
103        "path": "edge_knows.json",
104        "file_filter": {
105          "extensions": [
106            "*"
107          ]
108        },
109        "format": "JSON",
110        "delimiter": null,
111        "date_format": "yyyy-MM-dd HH:mm:ss",
112        "time_zone": "GMT+8",
113        "skipped_line": {
114          "regex": "(^#|^//).*|"
115        },
116        "compression": "NONE",
117        "header": null,
118        "charset": "UTF-8",
119        "list_format": null
120      },
121      "vertices": [],
122      "edges": [
123        {
124          "label": "knows",
125          "skip": false,
126          "source": [
127            "source_name"
128          ],
129          "unfold_source": false,
130          "target": [
131            "target_name"
132          ],
133          "unfold_target": false,
134          "field_mapping": {
135            "source_name": "name",
136            "target_name": "name"
137          },
138          "value_mapping": {},
139          "selected": [],
140          "ignored": [],
141          "null_values": [
142            ""
143          ],
144          "update_strategies": {}
145        }
146      ]
147    },
148    {
149      "id": "4",
150      "skip": false,
151      "input": {
152        "type": "FILE",
153        "path": "edge_created.json",
154        "file_filter": {
155          "extensions": [
156            "*"
157          ]
158        },
159        "format": "JSON",
160        "delimiter": null,
161        "date_format": "yyyy-MM-dd HH:mm:ss",
162        "time_zone": "GMT+8",
163        "skipped_line": {
164          "regex": "(^#|^//).*|"
165        },
166        "compression": "NONE",
167        "header": null,
168        "charset": "UTF-8",
169        "list_format": null
170      },
171      "vertices": [],
172      "edges": [
173        {
174          "label": "created",
175          "skip": false,
176          "source": [
177            "source_name"
178          ],
179          "unfold_source": false,
180          "target": [
181            "target_name"
182          ],
183          "unfold_target": false,
184          "field_mapping": {
185            "source_name": "name",
186            "target_name": "name"
187          },
188          "value_mapping": {},
189          "selected": [],
190          "ignored": [],
191          "null_values": [
192            ""
193          ],
194          "update_strategies": {}
195        }
196      ]
197    }
198  ]
199}

 1{
 2  "vertices": [
 3    {
 4      "label": "person",
 5      "input": {
 6        "type": "file",
 7        "path": "vertex_person.csv",
 8        "format": "CSV",
 9        "header": ["name", "age", "city"],
10        "charset": "UTF-8"
11      }
12    },
13    {
14      "label": "software",
15      "input": {
16        "type": "file",
17        "path": "vertex_software.csv",
18        "format": "CSV"
19      }
20    }
21  ],
22  "edges": [
23    {
24      "label": "knows",
25      "source": ["source_name"],
26      "target": ["target_name"],
27      "input": {
28        "type": "file",
29        "path": "edge_knows.json",
30        "format": "JSON"
31      },
32      "field_mapping": {
33        "source_name": "name",
34        "target_name": "name"
35      }
36    },
37    {
38      "label": "created",
39      "source": ["source_name"],
40      "target": ["target_name"],
41      "input": {
42        "type": "file",
43        "path": "edge_created.json",
44        "format": "JSON"
45      },
46      "field_mapping": {
47        "source_name": "name",
48        "target_name": "name"
49      }
50    }
51  ]
52}

映射文件 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 版本的，使用方式如下：

1bin/mapping-convert.sh struct.json

会在 struct.json 的同级目录下生成一个 struct-v2.json。

bin 目录下还提供了 utf8-bom-to-utf8.sh，用于去掉单个数据文件、或目录下所有文件开头的 UTF-8 BOM。当 Windows 工具导出的 CSV 或 TEXT 文件因为首列表头带有不可见的 BOM 而解析失败时，可以用它处理：

1bin/utf8-bom-to-utf8.sh /path/to/file-or-dir

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: 本地文件或目录的路径，绝对路径或相对于 Loader 进程当前工作目录的相对路径，必填；为避免工作目录不同导致找不到文件，建议使用绝对路径；
  • file_filter: 从path中筛选复合条件的文件，复合结构，目前只支持配置扩展名，用子节点extensions表示，默认为”*"，表示保留所有文件；
  • format: 本地文件的格式，可选值为 CSV、TEXT 及 JSON，必须大写，默认为 CSV，选填；
  • header: 文件各列的列名，如不指定则以数据文件第一行作为 header；显式指定时，首行若与 header 完全相同，默认仍会跳过，详见 has_header；JSON 文件不需要指定 header，选填；
  • has_header: 对 CSV 和 TEXT 格式，如果某个文件的首行与 header 完全相同，该行会被丢弃，这样目录下每个分片文件重复的表头不会被当作数据导入。如果分片文件的首行是恰好与 header 相同的真实数据，可以设为 false 关闭这个检查，选填；
  • delimiter: 文件行的列分隔符。默认值取决于format：CSV 为逗号","，TEXT 为制表符"\t"；CSV 只接受逗号。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描述。默认正则为(^#|^//).*|，即跳过以#或//开头的行以及空行；如果需要保留这类行，把regex改为一个不匹配任何行的表达式即可，选填；
  • compression: 文件的压缩格式，可选值为 NONE、GZIP、BZ2、XZ、LZMA、SNAPPY_RAW、SNAPPY_FRAMED、Z、DEFLATE、LZ4_BLOCK、LZ4_FRAMED、ORC 和 PARQUET，默认为 NONE，表示非压缩文件，选填；ORC 和 PARQUET 的 header 匹配不区分大小写；
  • list_format: 当文件 (非 JSON ) 的某列是集合结构时（对应图中的 PropertyKey 的 Cardinality 为 Set 或 List），可以用此项设置该列的起始符、分隔符、结束符，复合结构：
    • start_symbol: 集合结构列的起始符 (默认值是空字符串 "", JSON 格式目前不支持指定)
    • elem_delimiter: 集合结构列的分隔符 (默认值是 |, 且不能与delimiter相同; JSON 格式目前只支持原生,分隔)
    • end_symbol: 集合结构列的结束符 (默认值是空字符串 "", JSON 格式目前不支持指定)
    • ignored_elems: 拆分之后要丢弃的元素，默认值是 [""]，即忽略空元素

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），必填；
• hdfs_site_path: HDFS 集群的 hdfs-site.xml 文件路径，选填；
• dir_filter: 当path是目录时，决定递归进入哪些子目录，复合结构，选填：
  • include_regex: 只读取目录名匹配该正则的目录，默认为空，即不作限制；
  • exclude_regex: 跳过目录名匹配该正则的目录，默认为空；
• kerberos_config: 访问开启了 Kerberos 认证的 HDFS 集群时的配置，复合结构，选填：
  • enable: 是否使用 Kerberos 认证，默认为 false；
  • krb5_conf: krb5.conf 文件路径，enable 为 true 时必填；
  • principal: Kerberos principal，enable 为 true 时必填；
  • keytab: keytab 文件路径，enable 为 true 时必填；

3.3.2.3 JDBC 输入源

前面说到过支持多种关系型数据库，但由于它们的映射结构非常相似，故统称为 JDBC 输入源，然后用vendor节点区分不同的数据库。

• type: 输入源类型，必须填 jdbc 或 JDBC，必填；
• vendor: 数据库类型，可选项为 [MySQL、PostgreSQL、Oracle、SQLServer]，不区分大小写，必填；
• driver: JDBC driver 类名，选填；不填时使用vendor对应的默认 driver，见下面各表；
• url: jdbc 要连接的数据库的 url，必填；
• database: 要连接的数据库名，必填；
• schema: 要连接的 schema 名，不同的数据库要求不一样，下面详细说明；
• table: 要连接的表名，custom_sql 和 table 参数必须填其中一个；
• custom_sql: 自定义 SQL 语句，custom_sql 和 table 参数必须填其中一个；
• username: 连接数据库的用户名，必填；
• password: 连接数据库的密码，必填；
• where: 附加到生成的 select 语句上的过滤条件，不需要写 where 关键字，选填；
• batch_size: 按页获取表数据时的一页的大小，默认为 500，选填；

MYSQL

schema: 可空，若填写必须与 database 的值一样

POSTGRESQL

schema: 可空，默认值为“public”

ORACLE

schema: 可空，默认值为大写形式的用户名

SQLSERVER

schema: 必填

3.3.2.4 Kafka 输入源

• type：输入源类型，必须填 kafka 或 KAFKA，必填；
• bootstrap_server：kafka bootstrap server 列表，必填；
• topic：订阅的 topic，必填；
• group：Kafka 消费者组，必填；
• from_beginning：设置 Kafka 的 auto.offset.reset；true 对应 earliest，false 对应 latest，默认为 false。该策略仅在消费组没有已提交 offset，或已提交 offset 不再有效时生效；已有有效 offset 时会从该 offset 继续读取；
• format：每条消息的格式，可选值为 CSV、TEXT 及 JSON，必须大写，必填；
• header：消息各列的列名；loader 不会从 topic 中读取表头行，因此 CSV 和 TEXT 格式必须指定，JSON 消息则不需要；
• delimiter：消息的列分隔符，仅 TEXT 格式使用，CSV 固定以,分隔，选填；
• charset：消息的编码字符集，默认 UTF-8，选填；
• date_format：自定义的日期格式，默认值为 yyyy-MM-dd HH:mm:ss，选填；如果日期是以时间戳的形式呈现的，此项须写为 timestamp（固定写法）；
• extra_date_formats：自定义的其他日期格式列表，默认为空，选填；列表中每一项都是一个 date_format 指定日期格式的备用日期格式；
• time_zone：置日期数据是处于哪个时区的，默认值为 GMT+8，选填；
• skipped_line：当前 master 的 KafkaReader 未实现该过滤，配置此字段不会跳过 Kafka 消息；每条消息仍会直接交给所选格式的解析器，空行或注释行可能因此触发解析错误。需要过滤时请在写入 Kafka 前或消费侧预处理；
• batch_size：单次拉取的最大记录数（max.poll.records），默认为 500，选填；
• early_stop：某次从 Kafka broker 拉取的记录为空，停止任务，默认为 false，仅用于调试，选填；

3.3.2.5 GRAPH 输入源

GRAPH 输入源从另一个 HugeGraph 图（通过 HugeGraph-PD 访问）读取顶点和边，并写入目标图。当映射文件中出现 GRAPH 输入源时，该文件中所有未被跳过的输入源都必须是 GRAPH 类型，并且导入期间 loader 会把目标图切换为 RESTORING 模式。

• type：输入源类型，必须填 graph 或 GRAPH，必填；
• graphspace：源图空间名称，必填；
• graph： 源图名称，必填；
• username：HugeGraph 用户名；为空时使用命令行参数 --username；
• password：HugeGraph 密码；为空时使用命令行参数 --password；
• selected_vertices：要复制的顶点 label 列表，每一项形如 {"label": "...", "properties": [...], "query": {...}}，其中 properties 限定要复制的属性，query 是传给源图的可选过滤条件；
• ignored_vertices：要跳过的顶点 label 列表，每一项形如 {"label": "...", "properties": [...]}；
• selected_edges：要复制的边 label 列表，每一项结构与 selected_vertices 相同；
• ignored_edges：要跳过的边 label 列表，每一项结构与 ignored_vertices 相同；
• pd-peers：源集群的 HugeGraph-PD 节点地址；为空时使用 --pd-peers；
• meta-endpoints：源集群 Meta 服务端点；为空时使用 --meta-endpoints；
• cluster：源集群名称；为空时使用 --cluster；
• batch_size：批量读取源图数据的批次大小，默认为500；

3.3.3 顶点和边映射

顶点和边映射的节点（JSON 文件中的一个 key）有很多相同的部分，下面先介绍相同部分，再分别介绍顶点映射和边映射的特有节点。

相同部分的节点

• label: 待导入的顶点/边数据所属的label，必填；
• skip: 是否跳过该顶点/边映射，输入源和其他映射不受影响，默认为 false，选填；
• 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 种 : (需要全大写)

1. 数值累加 : SUM
2. 两个数字/日期取更大的: BIGGER
3. 两个数字/日期取更小: SMALLER
4. Set属性取并集：UNION
5. Set属性取交集：INTERSECTION
6. List属性追加元素：APPEND
7. List/Set属性删除元素：ELIMINATE
8. 覆盖已有属性：OVERRIDE

注意： 如果新导入的属性值为空，会采用已有的旧数据而不会采用空值，效果可以参考如下示例

 1// JSON 文件中以如下方式指定更新策略
 2{
 3  "vertices": [
 4    {
 5      "label": "person",
 6      "update_strategies": {
 7        "age": "SMALLER",
 8        "set": "UNION"
 9      },
10      "input": {
11        "type": "file",
12        "path": "vertex_person.txt",
13        "format": "TEXT",
14        "header": ["name", "age", "set"]
15      }
16    }
17  ]
18}
19
20// 1.写入一行带 OVERRIDE 更新策略的数据 (这里 null 代表空)
21'a b null null'
22
23// 2.再写一行
24'null null c d'
25
26// 3.最后可以得到
27'a b c d'   
28
29// 如果没有更新策略，则会得到
30'null null c d'

注意 : 采用了批量更新的策略后, 磁盘读请求数会大幅上升, 导入速度相比纯写覆盖会慢数倍 (此时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 参数说明

映射文件选项 --file（-f）是必填项，其他选项使用默认值。有效的最简调用为：

1bin/hugegraph-loader.sh --file struct.json

启动脚本也支持 JCommander 原生的 @file 语法。在 loader.args 中把每个选项及其值分别写在单独一行：

1--file
2struct.json

1bin/hugegraph-loader.sh @loader.args

这与上面的最简调用等价。参数中的相对路径以 Loader 进程的工作目录为基准。 若参数文件包含凭据，使用 chmod 0600 loader.args 把权限限制为 0600；@file 调用让这些值不出现在进程参数中。 Loader 必须能够创建并写入以映射文件前缀命名的进度目录。 从只读 Kubernetes ConfigMap 挂载映射文件时，先把映射复制到可写卷中再运行 Loader。

3.4.2 断点续导模式

通常情况下，Loader 任务都需要较长时间执行，如果因为某些原因导致导入中断进程退出，而下次希望能从中断的点继续导，这就是使用断点续导的场景。

设置 --incremental-mode 为 true 即可从进度文件续导。Loader 在导入成功或正常停止后关闭时写入进度；意外失败可能阻止该写入。 进度文件位于 ${struct} 目录下，文件名形如 load-progress_${timestamp} ，${struct} 为映射文件的前缀，${timestamp} 为导入开始 的时刻，格式为 yyyyMMdd-HHmmss。比如：在 2019-10-10 12:30:30 开始的一次导入任务，使用的映射文件为 struct-example.json，则进度文件的路径为与 struct-example.json 同级的 struct-example/load-progress_20191010-123030。当目录下存在多个进度文件时，续导会读取按文件名排序的最后一个，也就是最新的那个。

注意：导入成功或正常停止（包括达到错误上限）后会写入进度文件，与 --incremental-mode 或 --print-progress 是否打开无关。 意外失败导致导入中止时，可能不会写入进度文件。

如果数据文件格式都是合法的，是用户自己停止（CTRL + C 或 kill，kill -9 不支持）的导入任务，也就是说没有错误记录的情况下，下一次导入只需要设置为断点续导即可。

但如果是因为太多数据不合法或者网络异常，达到了 –max-read-errors、–max-parse-errors 或 –max-insert-errors 的限制，Loader 会把这些失败的原始行记录到 失败文件中，用户对失败文件中的数据行修改后，设置 –failure-mode 为 true 即可把这些"失败文件"也当作输入源进行导入（不影响正常的文件的导入）， 当然如果修改后的数据行仍然有问题，则会被再次记录到失败文件中（不用担心会有重复行，关闭文件时会去重）。失败模式下上述三个错误上限会被解除，因此会扫描整个失败文件。

每个输入源（即映射文件 structs 中的每一项）都会有自己的失败文件，文件名为该输入源的 id 加后缀 .error，保存在 ${struct}/failure-data 目录下。 每一条失败记录写为两行：一行以 #### READ ERROR:、#### PARSE ERROR: 或 #### INSERT ERROR: 开头的提示行，紧接着是原始数据行。当输入源有 header 时，header 会以 JSON 形式写入同目录下的 ${id}.header 文件，以便失败文件能按正确的列重新读取。 比如映射文件中 id 为 1 的输入源包含顶点映射 person，id 为 3 的输入源包含边映射 knows，它们各有一些错误行，当 Loader 退出后，在 ${struct}/failure-data 目录下会看到如下文件：

• 1.error: 输入源 1 的失败数据行，每行前面都有对应的提示行
• 1.header: 输入源 1 的 header，仅当该输入源有 header 时才会生成
• 3.error: 输入源 3 的失败数据行
• 3.header: 输入源 3 的 header

内容为空的 .error 文件会在 Loader 退出时删除，因此只有真正出现失败行的输入源才会留下文件。增量模式下新的失败行会追加到已有文件，其他模式下该文件会被重新写入。

3.4.3 logs 目录文件说明

程序执行过程中各日志及错误数据会写入 hugegraph-loader.log 文件中。

3.4.4 执行命令

运行 bin/hugegraph-loader.sh 并传入参数

1bin/hugegraph-loader.sh -g {GRAPH_NAME} -f ${INPUT_DESC_FILE} -s ${SCHEMA_FILE} -h {HOST} -p {PORT}

脚本在设置了 JAVA_HOME 时使用其中的 JVM，否则使用 PATH 上的 java。它会把 JVM_OPTS 环境变量的内容，以及 -Xmx10g 和由 lib/ 生成的 classpath 一起传给 JVM，因此需要追加 JVM 参数时可以设置 JVM_OPTS。日志由 conf/log4j2.xml 配置。

3.4.5 最小本地文件导入示例

先确保 HugeGraph Server 已启动，当前用户可以访问 DEFAULT 图空间中的 hugegraph 图，并有权限创建 Schema 和写入数据。若 Server 已启用认证，在命令中增加对应的 --username、--password 或 --token。本例只需本地文件，不依赖 Kafka、HDFS 或 JDBC。

进入解压后的 Loader 安装目录，再创建数据、Schema 和 2.0 格式的映射文件：

 1mkdir -p demo-loader
 2
 3cat > demo-loader/people.csv <<'EOF'
 4docs-smoke-alice,29
 5docs-smoke-bob,31
 6EOF
 7
 8cat > demo-loader/schema.groovy <<'EOF'
 9schema.propertyKey("docs_name").asText().ifNotExist().create()
10schema.propertyKey("docs_age").asInt().ifNotExist().create()
11schema.vertexLabel("docs_smoke_person").properties("docs_name", "docs_age").primaryKeys("docs_name").ifNotExist().create()
12EOF
13
14cat > demo-loader/struct.json <<'EOF'
15{
16  "version": "2.0",
17  "structs": [
18    {
19      "id": "people",
20      "input": {
21        "type": "FILE",
22        "path": "demo-loader/people.csv",
23        "format": "CSV",
24        "header": ["docs_name", "docs_age"]
25      },
26      "vertices": [
27        {"label": "docs_smoke_person"}
28      ],
29      "edges": []
30    }
31  ]
32}
33EOF

people.csv 没有表头行，列名由映射文件的 header 提供。映射文件中的本地路径相对于运行命令时的工作目录。仍在 Loader 安装目录中执行导入；如果 Server 在其他容器中，请把 --host 改为 Loader 能访问到的 Server 地址。

1bin/hugegraph-loader.sh \
2  --graphspace DEFAULT --graph hugegraph \
3  --file demo-loader/struct.json --schema demo-loader/schema.groovy \
4  --host 127.0.0.1 --port 8080

本例用独立的 docs_smoke_person 标签和 docs_* 属性，避免与预置的 person 样例数据冲突。成功时统计中应显示顶点写入成功数为 2、边写入成功数为 0。也可以在 Hubble 的 Gremlin 工作台查询 g.V().hasLabel('docs_smoke_person').values('docs_name')，结果应包含 docs-smoke-alice 和 docs-smoke-bob。

4 完整示例

下面给出的是 hugegraph-loader 包中 example 目录下的例子。(GitHub 地址)

4.1 准备数据

顶点文件：example/file/vertex_person.csv

1marko,29,Beijing
2vadas,27,Hongkong
3josh,32,Beijing
4peter,35,Shanghai
5"li,nary",26,"Wu,han"
6tom,null,NULL

顶点文件：example/file/vertex_software.txt

1id|name|lang|price|ISBN
21|lop|java|328|ISBN978-7-107-18618-5
32|ripple|java|199|ISBN978-7-100-13678-5

边文件：example/file/edge_knows.json

1{"source_name": "marko", "target_name": "vadas", "date": "20160110", "weight": 0.5}
2{"source_name": "marko", "target_name": "josh", "date": "20130220", "weight": 1.0}

边文件：example/file/edge_created.json

1{"source_name": "marko", "target_id": 1, "date": "2017-12-10", "weight": 0.4}
2{"source_name": "josh", "target_id": 1, "date": "2009-11-11", "weight": 0.4}
3{"source_name": "josh", "target_id": 2, "date": "2017-12-10", "weight": 1.0}
4{"source_name": "peter", "target_id": 1, "date": "2017-03-24", "weight": 0.2}

4.2 编写 schema

 1schema.propertyKey("name").asText().ifNotExist().create();
 2schema.propertyKey("age").asInt().ifNotExist().create();
 3schema.propertyKey("city").asText().ifNotExist().create();
 4schema.propertyKey("weight").asDouble().ifNotExist().create();
 5schema.propertyKey("lang").asText().ifNotExist().create();
 6schema.propertyKey("date").asText().ifNotExist().create();
 7schema.propertyKey("price").asDouble().ifNotExist().create();
 8
 9schema.vertexLabel("person").properties("name", "age", "city").primaryKeys("name").nullableKeys("age", "city").ifNotExist().create();
10schema.vertexLabel("software").useCustomizeNumberId().properties("name", "lang", "price").ifNotExist().create();
11
12schema.indexLabel("personByAge").onV("person").by("age").range().ifNotExist().create();
13schema.indexLabel("personByCity").onV("person").by("city").secondary().ifNotExist().create();
14schema.indexLabel("personByAgeAndCity").onV("person").by("age", "city").secondary().ifNotExist().create();
15schema.indexLabel("softwareByPrice").onV("software").by("price").range().ifNotExist().create();
16
17schema.edgeLabel("knows").sourceLabel("person").targetLabel("person").properties("date", "weight").ifNotExist().create();
18schema.edgeLabel("created").sourceLabel("person").targetLabel("software").properties("date", "weight").ifNotExist().create();
19
20schema.indexLabel("createdByDate").onE("created").by("date").secondary().ifNotExist().create();
21schema.indexLabel("createdByWeight").onE("created").by("weight").range().ifNotExist().create();
22schema.indexLabel("knowsByWeight").onE("knows").by("weight").range().ifNotExist().create();

person 使用 name 作为主键；Tom 的 age 和 city 会被 null_values 去掉，因此这两个属性必须允许为空。 software 使用自定义数值 ID，映射中的 id 和 created.target_id 分别对应顶点 ID 及边的目标 ID。 请在未包含同名 Schema 的空图中执行，避免 ifNotExist() 保留已有的不兼容定义。

4.3 编写输入源映射文件example/file/struct.json

 1{
 2  "vertices": [
 3    {
 4      "label": "person",
 5      "input": {
 6        "type": "file",
 7        "path": "example/file/vertex_person.csv",
 8        "format": "CSV",
 9        "header": ["name", "age", "city"],
10        "charset": "UTF-8",
11        "skipped_line": {
12          "regex": "(^#|^//).*"
13        }
14      },
15      "null_values": ["NULL", "null", ""]
16    },
17    {
18      "label": "software",
19      "input": {
20        "type": "file",
21        "path": "example/file/vertex_software.txt",
22        "format": "TEXT",
23        "delimiter": "|",
24        "charset": "GBK"
25      },
26      "id": "id",
27      "ignored": ["ISBN"]
28    }
29  ],
30  "edges": [
31    {
32      "label": "knows",
33      "source": ["source_name"],
34      "target": ["target_name"],
35      "input": {
36        "type": "file",
37        "path": "example/file/edge_knows.json",
38        "format": "JSON",
39        "date_format": "yyyyMMdd"
40      },
41      "field_mapping": {
42        "source_name": "name",
43        "target_name": "name"
44      }
45    },
46    {
47      "label": "created",
48      "source": ["source_name"],
49      "target": ["target_id"],
50      "input": {
51        "type": "file",
52        "path": "example/file/edge_created.json",
53        "format": "JSON",
54        "date_format": "yyyy-MM-dd"
55      },
56      "field_mapping": {
57        "source_name": "name"
58      }
59    }
60  ]
61}

4.4 执行命令导入

1sh bin/hugegraph-loader.sh -g hugegraph -f example/file/struct.json -s example/file/schema.groovy

导入结束后，会出现类似如下统计信息：

 1vertices/edges has been loaded this time : 8/6
 2--------------------------------------------------
 3count metrics
 4     input read success            : 14
 5     input read failure            : 0
 6     vertex parse success          : 8
 7     vertex parse failure          : 0
 8     vertex insert success         : 8
 9     vertex insert failure         : 0
10     edge parse success            : 6
11     edge parse failure            : 0
12     edge insert success           : 6
13     edge insert failure           : 0

4.5 使用 docker 导入

4.5.1 使用 docker exec 直接导入数据

4.5.1.1 数据准备

如果仅仅尝试使用 loader, 我们可以使用内置的 example 数据集进行导入，无需自己额外准备数据

如果使用自定义的数据，则在使用 loader 导入数据之前，我们需要将数据复制到容器内部。

首先我们可以根据 4.1-4.3 的步骤准备数据，将准备好的数据通过 docker cp 复制到 loader 容器内部。

假设我们已经按照上述的步骤准备好了对应的数据集，存放在 hugegraph-dataset 文件夹下，文件结构如下：

1tree -f hugegraph-dataset/
2
3hugegraph-dataset
4├── hugegraph-dataset/edge_created.json
5├── hugegraph-dataset/edge_knows.json
6├── hugegraph-dataset/schema.groovy
7├── hugegraph-dataset/struct.json
8├── hugegraph-dataset/vertex_person.csv
9└── hugegraph-dataset/vertex_software.txt

将文件复制到容器内部

1docker cp hugegraph-dataset loader:/loader/dataset
2docker exec -it loader ls /loader/dataset
3
4edge_created.json  edge_knows.json  schema.groovy  struct.json  vertex_person.csv  vertex_software.txt

4.5.1.2 数据导入

以内置的 example 数据集为例，我们可以使用以下的命令对数据进行导入。

如果需要导入自己准备的数据集，则只需要修改 -f 配置脚本的路径 以及 -s schema 文件路径即可。

其他的参数可以参照 3.4.1 参数说明

1docker exec -it loader bin/hugegraph-loader.sh -g hugegraph -f example/file/struct.json -s example/file/schema.groovy -h server -p 8080

如果导入用户自定义的数据集，按照刚才的例子，则使用：

1docker exec -it loader bin/hugegraph-loader.sh -g hugegraph -f /loader/dataset/struct.json -s /loader/dataset/schema.groovy -h server -p 8080

自定义数据集的 struct.json 还需将每个 input.path 改为容器内实际路径，例如 /loader/dataset/vertex_person.csv。 只修改 -f 和 -s 不会改变数据文件的解析路径。

如果 loader 和 server位于同一 docker 网络，则可以指定 -h {server_container_name}, 否则需要指定 server的宿主机的 ip (在我们的例子中， server_container_name 为 server).

然后我们可以观察到结果：

 1HugeGraphLoader worked in NORMAL MODE
 2vertices/edges loaded this time : 8/6
 3--------------------------------------------------
 4count metrics
 5    input read success            : 14                  
 6    input read failure            : 0                   
 7    vertex parse success          : 8                   
 8    vertex parse failure          : 0                   
 9    vertex insert success         : 8                   
10    vertex insert failure         : 0                   
11    edge parse success            : 6                   
12    edge parse failure            : 0                   
13    edge insert success           : 6                   
14    edge insert failure           : 0                   
15--------------------------------------------------
16meter metrics
17    total time                    : 0.199s              
18    read time                     : 0.046s              
19    load time                     : 0.153s              
20    vertex load time              : 0.077s              
21    vertex load rate(vertices/s)  : 103                 
22    edge load time                : 0.112s              
23    edge load rate(edges/s)       : 53   

也可以使用 curl 或者 hubble观察导入结果，此处以 curl 为例：

以下使用支持 GraphSpace 的 Server API；旧版 Server 的路径需去掉 /graphspaces/DEFAULT。

1curl --compressed "http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices"
2{"vertices":[{"id":1,"label":"software","type":"vertex","properties":{"name":"lop","lang":"java","price":328.0}},{"id":2,"label":"software","type":"vertex","properties":{"name":"ripple","lang":"java","price":199.0}},{"id":"1:tom","label":"person","type":"vertex","properties":{"name":"tom"}},{"id":"1:josh","label":"person","type":"vertex","properties":{"name":"josh","age":32,"city":"Beijing"}},{"id":"1:marko","label":"person","type":"vertex","properties":{"name":"marko","age":29,"city":"Beijing"}},{"id":"1:peter","label":"person","type":"vertex","properties":{"name":"peter","age":35,"city":"Shanghai"}},{"id":"1:vadas","label":"person","type":"vertex","properties":{"name":"vadas","age":27,"city":"Hongkong"}},{"id":"1:li,nary","label":"person","type":"vertex","properties":{"name":"li,nary","age":26,"city":"Wu,han"}}]}

如果想检查边的导入结果，可以使用 curl --compressed "http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges"

4.5.2 进入 docker 容器进行导入

除了直接使用 docker exec 导入数据，我们也可以进入容器进行数据导入，基本流程与 4.5.1 相同

使用 docker exec -it loader bash进入容器内部，并执行命令

1sh bin/hugegraph-loader.sh -g hugegraph -f example/file/struct.json -s example/file/schema.groovy -h server -p 8080

执行的结果如 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）

示例：

1sh bin/hugegraph-spark-loader.sh --master yarn \
2--deploy-mode cluster --name spark-hugegraph-loader --file ./hugegraph.json \
3--username admin --token admin --host xx.xx.xx.xx --port 8093 \
4--graph graph-test --num-executors 6 --executor-cores 16 --executor-memory 15g

bin/hugegraph-spark-loader.sh 通过 ${SPARK_HOME}/bin/spark-submit 提交 org.apache.hugegraph.loader.spark.HugeGraphSparkLoader，因此 SPARK_HOME 必须指向一个 Spark 安装目录。lib/ 下的所有 jar 都会加入 classpath。Spark 应用名默认为 hugegraph-spark-loader，可以通过 APP_NAME 环境变量修改。

bin/get-params.sh 负责拆分命令行：只有下列参数会交给 loader，其余参数原样传给 spark-submit。该拆分只识别参数全称，因此 -f、-g 这类缩写不会被识别。

1--graph --schema --host --port --username --token --protocol
2--trust-store-file --trust-store-password --clear-all-data --clear-timeout
3--incremental-mode --failure-mode --batch-insert-threads --single-insert-threads
4--max-conn --max-conn-per-route --batch-size --max-parse-errors --max-insert-errors
5--timeout --shutdown-timeout --retry-times --retry-interval --check-vertex
6--print-progress --dry-run --sink-type --vertex-partitions --edge-partitions --help

--file 单独处理：使用 --deploy-mode cluster 时，映射文件会通过 --files 分发到 executor，loader 只收到它的文件名；其他情况下路径原样传入。

该模式下 loader 只读取 FILE、HDFS 和 JDBC 输入源，KAFKA 和 GRAPH 输入源会被拒绝。

默认情况下（--sink-type true），每个 Spark 分区各自创建一个 HugeClient，通过 HugeGraph server API 写入顶点和边。使用 --sink-type false 时，loader 会生成 HFile 并直接 bulkload 到 HBase，此时表名和 ZooKeeper 配置取自 --vertex-table-name、--edge-table-name、--hbase-zk-quorum、--hbase-zk-port、--hbase-zk-parent、--vertex-partitions 和 --edge-partitions。

4.7 使用 flink-cdc-loader 导入

当前源码使用 Flink 1.13.5、flink-connector-mysql-cdc 2.2.1 和 Scala 2.12；其他组合需自行验证。

bin/hugegraph-flinkcdc-loader.sh 通过 ${FLINK_HOME}/bin/flink run 提交 org.apache.hugegraph.loader.flink.HugeGraphFlinkCDCLoader，因此必须设置 FLINK_HOME。该任务用 Flink CDC 捕获 MySQL 的变更事件并应用到图上，从而让图与源表保持同步。

映射文件格式与命令行 loader 相同，但每个输入源都必须是 MySQL 的 JDBC 输入源：loader 从中读取 url、database、table、username 和 password，并从 url 解析出主机和端口。顶点和边映射的用法不变。3.4.1 中的 --cdc-flush-interval 和 --cdc-sink-parallelism 只在该模式下生效。

命令行同样由 bin/get-params.sh 按 4.6 的方式拆分，非 loader 参数会传给 flink run。

示例：

1sh bin/hugegraph-flinkcdc-loader.sh --file ./mysql-cdc.json \
2--host xx.xx.xx.xx --port 8080 --graph hugegraph --username admin --token admin

4 - 图导入

需要把文件、数据库或消息数据写入 HugeGraph 时，从这里选择工具。直接导入可使用 Loader；已有 Source、Transform、Sink 管道时使用 SeaTunnel Sink；Spark 作业可使用 Spark Connector。

• 使用 Loader 导入数据
• 使用 SeaTunnel Sink 导入图数据
• 使用 Spark Connector 读写图数据

4.1 - 使用 SeaTunnel Sink 导入图数据

SeaTunnel 可以把数据库、Kafka 等数据源接入 HugeGraph。连接器分为两部分：Source 负责读取，Sink 负责写入^[1][2]，中间可以接 SeaTunnel 的数据转换组件。需要从 HugeGraph 导出或迁移数据时，请查看SeaTunnel Source 导出与迁移文档。

版本要求：本文面向 SeaTunnel 3.0+。 所有示例使用 SeaTunnel 3.0+ 提供的 mappings 配置。

点击配图可查看原图。

1 与 Loader 和 Tools 的区别

HugeGraph-Loader 适合把常见数据直接导入 HugeGraph；HugeGraph-Tools 主要用于单机图管理、备份和导出；SeaTunnel 则把任务组织成 Source → Transform → Sink，适合复用已有的连接器、转换步骤和数据处理管道。

表格标记

✅ 原生支持；⚠️ 有条件支持，或需要额外组件/外部平台；❌ 不提供该能力

SeaTunnel 覆盖 Loader 的图导入和 Tools 的导出、迁移场景，可以把两类任务放进同一条可扩展管道，还支持 SQL-CDC 和数十种输入输出类型。默认情况下，Loader 和 Tools 都在单机运行；SeaTunnel 同时支持单机和分布式部署，可随着数据量和任务数量扩展。Tools 的 schedule-backup 可以创建 crontab 任务，但它不负责统一的任务编排和资源管理。

已有 Spark/Flink 每日任务

HugeGraph Source 和 Sink 在 SeaTunnel 3.0+ 中都支持 SeaTunnel Engine（Zeta）、Spark 和 Flink。若把每日任务改成 SeaTunnel 作业，并用对应引擎提交，数据可以在 Source → Transform → Sink 之间直接传递，不需要先落盘再交给 Loader。若保留现有 Spark/Flink DAG，SeaTunnel 不会自动接管内存中的 DataFrame 或 Stream，需要改造成 SeaTunnel 作业，或让 Source 读取已有系统中的数据

Loader 和 Tools 的优势是专注、直接、上手快。需要直接导入图数据时可先用 Loader；需要备份、恢复、导出或日常运维时可用 Tools。如果已经有 SeaTunnel 作业，通常在原管道中接入 HugeGraph 更方便。需要更高导入吞吐时，Loader 的 bypass-server 和其他导入优化更合适；Loader 在特定后端、数据规模和硬件条件下实测峰值可达 100～200 万条/秒，不能直接当作通用性能承诺，仍需单独压测。新建 SeaTunnel 任务使用 3.0+ 和 mappings。使用其他版本时，请重新核对连接器配置。

2 准备环境

2.1 获取 SeaTunnel 3.0+

使用 JDK 11 并设置 JAVA_HOME；官方部署文档 列出的前置要求为 Java 8 或 11。从官方下载页^[4] 选择 3.0+ 二进制发行包，并使用页面提供的校验文件或签名验证下载包。 下面以 3.0.0 为例，请将 SEATUNNEL_VERSION 改为实际下载的发行版本。

1export SEATUNNEL_VERSION=3.0.0
2tar -xzf "apache-seatunnel-${SEATUNNEL_VERSION}-bin.tar.gz"
3cd "apache-seatunnel-${SEATUNNEL_VERSION}"

二进制发行包不包含连接器插件。在 config/plugin_config 中选择示例需要的连接器：

1--seatunnel-connectors--
2connector-hugegraph
3connector-jdbc
4connector-kafka
5--end--

按官方插件安装说明^[5] 安装同版本的已发布插件：

1sh bin/install-plugin.sh "${SEATUNNEL_VERSION}"

后续命令均在该安装目录执行，引擎和连接器插件保持相同版本。 本文使用自带的 Zeta 引擎和 local 模式^[6][7]。确认 connectors/ 中有 HugeGraph，以及所需的 JDBC 或 Kafka 插件^[11][12]。 JDBC 示例还需将 MySQL 驱动 JAR 放入 lib/，驱动类为 com.mysql.cj.jdbc.Driver。

2.2 准备 HugeGraph 和数据源

先启动 HugeGraph Server，创建可用于测试的图。本文示例使用 hugegraph 图、DEFAULT 图空间，请按服务端实际配置修改；图空间名称区分大小写。启用了身份验证时，在 HugeGraph Source 和 Sink 中填写 username、password。

下面的图模型贯穿 JDBC 和 Kafka 示例。mappings 默认会创建缺失的 PropertyKey、VertexLabel 和 EdgeLabel；已有图模型必须与配置兼容。

所有示例中的 mysql、kafka、hugegraph 都是占位主机名，需替换为 SeaTunnel 运行环境可访问的地址。容器中的 127.0.0.1 指向容器自身；同一 Docker 网络可使用服务名。host 只填主机名或 IP，端口单独填写。

3 从关系库导入（sql2graph）

用两个任务完成导入：先把 person 表写成顶点，再把 knows 表写成边。这样写边时，两个端点都已经存在。

3.1 导入顶点

在 MySQL 的 demo 数据库中准备示例数据，并让配置中的账号有读取权限：

1CREATE TABLE person (
2  name VARCHAR(64) PRIMARY KEY,
3  age INT NOT NULL
4);
5INSERT INTO person VALUES ('marko', 29), ('vadas', 27);

保存为 config/sql2graph-person.conf，将数据库账号和密码替换为实际值：

 1env {
 2  job.mode = "BATCH"
 3}
 4
 5source {
 6  Jdbc {
 7    url = "jdbc:mysql://mysql:3306/demo?useSSL=false&serverTimezone=UTC"
 8    driver = "com.mysql.cj.jdbc.Driver"
 9    username = "seatunnel"
10    password = "change_me"
11    query = "SELECT name, age FROM person ORDER BY name"
12  }
13}
14
15sink {
16  HugeGraph {
17    host = "hugegraph"
18    port = 8080
19    graph_name = "hugegraph"
20    graph_space = "DEFAULT"
21    batch_failure_fallback = false
22    mappings = [
23      {
24        type = "VERTEX"
25        label = "person"
26        idStrategy = "PRIMARY_KEY"
27        idFields = ["name"]
28        properties = ["name", "age"]
29      }
30    ]
31  }
32}

1./bin/seatunnel.sh --config ./config/sql2graph-person.conf -m local

在 Hubble 或 Gremlin 中检查结果，应能查到 marko 和 vadas 及其年龄：

1g.V().hasLabel('person').valueMap('name', 'age')

idFields = ["name"] 表示使用名字生成主键。重复导入同一个 name 会写到同一个顶点；properties 指定要写入的源字段。

3.2 导入边

准备关系表，其中两个端点字段对应前面导入的 person.name：

1CREATE TABLE knows (
2  source_name VARCHAR(64) NOT NULL,
3  target_name VARCHAR(64) NOT NULL,
4  since INT NOT NULL
5);
6INSERT INTO knows VALUES ('marko', 'vadas', 2010);

 1env {
 2  job.mode = "BATCH"
 3}
 4
 5source {
 6  Jdbc {
 7    url = "jdbc:mysql://mysql:3306/demo?useSSL=false&serverTimezone=UTC"
 8    driver = "com.mysql.cj.jdbc.Driver"
 9    username = "seatunnel"
10    password = "change_me"
11    query = "SELECT source_name, target_name, since FROM knows ORDER BY source_name, target_name"
12  }
13}
14
15sink {
16  HugeGraph {
17    host = "hugegraph"
18    port = 8080
19    graph_name = "hugegraph"
20    graph_space = "DEFAULT"
21    batch_failure_fallback = false
22    check_vertex = true
23    mappings = [
24      {
25        type = "EDGE"
26        label = "knows"
27        sourceConfig = {
28          label = "person"
29          idFields = ["source_name"]
30        }
31        targetConfig = {
32          label = "person"
33          idFields = ["target_name"]
34        }
35        fieldMapping = {
36          source_name = "name"
37          target_name = "name"
38        }
39        properties = ["since"]
40      }
41    ]
42  }
43}

确认顶点任务成功后，再执行边任务：

1./bin/seatunnel.sh --config ./config/sql2graph-knows.conf -m local

下面的查询应返回 marko 到 vadas 的 knows 边，属性 since 为 2010：

1g.V().has('person', 'name', 'marko').outE('knows').where(inV().has('name', 'vadas')).valueMap()

sourceConfig 和 targetConfig 指定端点字段，fieldMapping 将它们对应到顶点主键 name，properties = ["since"] 只写边属性。示例启用 check_vertex = true，并关闭失败后逐条跳过的回退（batch_failure_fallback = false）；端点不存在或写入失败时，任务会报错。

如果关系表只有数字外键，而图的主键使用姓名，请先在 SQL 中关联出姓名，再交给 Sink。MySQL CDC 接入方式见 MySQL CDC Source^[13]。

4 从 Kafka 导入（kafka2graph）

Kafka 适合持续接收事件。先创建 user-events topic，再写入以下 JSON 消息，每条消息对应一个 person 顶点：

1{"name":"marko","age":29}

保存为 config/kafka2graph.conf：

 1env {
 2  job.mode = "STREAMING"
 3  checkpoint.interval = 10000
 4  sink.flush.interval = 5000
 5}
 6
 7source {
 8  Kafka {
 9    bootstrap.servers = "kafka:9092"
10    topic = "user-events"
11    consumer.group = "hugegraph-import"
12    start_mode = "earliest"
13    format = "json"
14    schema = {
15      fields = {
16        name = "string"
17        age = "int"
18      }
19    }
20  }
21}
22
23sink {
24  HugeGraph {
25    host = "hugegraph"
26    port = 8080
27    graph_name = "hugegraph"
28    graph_space = "DEFAULT"
29    batch_failure_fallback = false
30    mappings = [
31      {
32        type = "VERTEX"
33        label = "person"
34        idStrategy = "PRIMARY_KEY"
35        idFields = ["name"]
36        properties = ["name", "age"]
37      }
38    ]
39  }
40}

1./bin/seatunnel.sh --config ./config/kafka2graph.conf -m local

用第 3.1 节的 Gremlin 查询检查数据。流式任务会持续运行；checkpoint.interval 每 10 秒保存一次任务状态，sink.flush.interval 让 Zeta 每 5 秒触发一次刷新，避免少量消息一直等到批次填满。

HugeGraph Sink 是 at-least-once（至少一次） 写入，故障恢复可能重放记录。使用 PRIMARY_KEY 能让相同 name 落到同一个顶点，但不等于所有更新操作都具备 exactly-once 语义。定时刷新由 Zeta 提供，不适用于 Spark 或 Flink 引擎。

5 常用配置与排错

下表适用于本文使用的 SeaTunnel 3.0+ 版本：

遇到问题时可按下面检查：

• 不识别 mappings 或找不到 HugeGraph Source：检查引擎与 HugeGraph connector 是否来自同一次 3.0+ 构建。
• 连接失败：检查主机、端口、图空间、认证信息，以及 SeaTunnel 所在环境能否访问服务。
• Schema 不兼容：检查标签的 ID 策略、属性类型和边端点。自动创建不会把已有 PRIMARY_KEY 标签改成 CUSTOMIZE_STRING。
• Kafka 少量数据未及时出现：确认使用 Zeta，并在 env 中设置 sink.flush.interval。此版本的 batch_interval_ms 仅为兼容保留，不能代替它。

6 选型小结

选工具时，先看要完成的工作：图管理、Gremlin、备份或克隆可用 Tools；直接导入图可先看 Loader；需要复用 Source、Transform、Sink 管道时选 SeaTunnel。使用 SeaTunnel 的图读取和迁移能力时，请按本文使用的 3.0+ 版本准备环境。

7 参考文档

HugeGraph 连接器

^[1] HugeGraph Source
^[2] HugeGraph Sink

配置与部署

^[3] HOCON 作业文件配置说明
^[4] SeaTunnel 3.0+ 正式版下载
^[5] 连接器插件安装说明
^[6] SeaTunnel 本地部署

执行引擎

^[7] SeaTunnel 引擎概览
^[8] SeaTunnel Spark 引擎
^[9] SeaTunnel Flink 引擎
^[10] Connector V2 多引擎说明

数据源连接器

^[11] JDBC Source
^[12] Kafka Source
^[13] MySQL CDC Source

5 - Tools 快速上手

1 HugeGraph-Tools概述

HugeGraph-Tools 是 HugeGraph 的自动化部署、管理和备份/还原组件。

测试指南：如需在本地运行 Tools 测试，请参考 工具链本地测试指南

2 获取 HugeGraph-Tools

HugeGraph-Tools 包含在 Toolchain 发布包中，可以下载发布包，也可以从源码编译。

• 下载二进制tar包
• 下载源码编译安装

2.1 下载二进制tar包

下载最新版本的 HugeGraph-Toolchain 包, 然后进入 tools 子目录

1export VERSION=1.7.0
2export ARCHIVE="apache-hugegraph-toolchain-incubating-${VERSION}"
3wget "https://downloads.apache.org/hugegraph/${VERSION}/${ARCHIVE}.tar.gz"
4tar zxf "${ARCHIVE}.tar.gz"
5# hugegraph-tools 位于 toolchain 发布包的子目录中，
6# 其版本后缀与发布包本身一致
7cd "${ARCHIVE}/apache-hugegraph-tools-incubating-${VERSION}"

2.2 下载源码编译安装

源码编译前请确保安装了wget命令

下载最新版本的 HugeGraph-Toolchain 源码包, 然后根目录编译或者单独编译 tool 子模块：

1# 1. get from github
2git clone https://github.com/apache/hugegraph-toolchain.git
3
4# 2. 下载发布版源码包
5export VERSION=1.7.0
6export ARCHIVE="apache-hugegraph-toolchain-incubating-${VERSION}"
7wget "https://downloads.apache.org/hugegraph/${VERSION}/${ARCHIVE}-src.tar.gz"

编译生成 tar 包:

1cd hugegraph-toolchain
2mvn package -pl hugegraph-tools -am -DskipTests -ntp

生成的 tar 包位于 hugegraph-tools/target/apache-hugegraph-tools-${version}.tar.gz，同时会在 hugegraph-tools/apache-hugegraph-tools-${version} 生成解压后的目录（包含 bin/ 和 lib/）

3 使用

3.1 功能概览

解压后，进入 apache-hugegraph-tools-${version} 目录，可以使用bin/hugegraph或者bin/hugegraph help来查看 usage 信息，使用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

1Usage: hugegraph [options] [command] [command options]

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
• –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 文件的密码
• –throw-mode，HugeGraph-Tools 出错时是否直接抛出异常，而不是打印错误信息后退出，默认为 false（主要用于测试）

连接协议由 –url 的 scheme 决定：使用 https://... 即通过 https 连接。–trust-store-file 和 –trust-store-password 只能在 –url 使用 https 时设置，–user 和 –password 必须同时提供或同时省略。

上述全局变量，也可以通过环境变量来设置。一种方式是在命令行使用 export 设置临时环境变量，在该命令行关闭之前均有效

下面两种写法查询同一个图的顶点总数，可按使用习惯任选一种。示例使用未启用鉴权的本地 Server；已启用鉴权时还需提供上述用户名和密码。

1./bin/hugegraph --url http://127.0.0.1:8080 --graph hugegraph gremlin-execute --script 'g.V().count()'

1export HUGEGRAPH_URL=http://127.0.0.1:8080
2export HUGEGRAPH_GRAPH=hugegraph
3./bin/hugegraph gremlin-execute --script 'g.V().count()'

另一种方式是在 bin/hugegraph 脚本中设置环境变量：

 1#!/bin/bash
 2
 3# Set environment here if needed
 4#export HUGEGRAPH_URL=
 5#export HUGEGRAPH_GRAPH=
 6#export HUGEGRAPH_USERNAME=
 7#export HUGEGRAPH_PASSWORD=
 8#export HUGEGRAPH_TIMEOUT=
 9#export HUGEGRAPH_TRUST_STORE_FILE=
10#export HUGEGRAPH_TRUST_STORE_PASSWORD=

bin/hugegraph 还会读取 JAVA_HOME（未设置时打印警告，https 需要它）和 JAVA_OPTIONS（JVM 参数，为空时脚本使用 -Xms512m，并根据机器空闲内存计算 -Xmx）。

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，选填项，新图的名称，默认为 g
  • –file 或者 -f，图配置文件的路径，文件内容会作为新图的配置发送给 HugeGraph-Server
• graph-clone，克隆已存在的图
  • –name 或者 -n，选填项，新克隆图的名称，默认为 g
  • –clone-graph-name，选填项，要克隆的源图名称，默认为 hugegraph
• graph-drop，删除图（不同于 graph-clear，这会完全删除图）
  • –confirm-message 或者 -c，必填项，确认消息 “I’m sure to drop the graph”，包括双引号

graph-create、graph-clone、graph-clear 和 graph-drop 会将 –timeout 提升到至少 300 秒。

当需要把备份的图原样恢复到一个新的图中的时候，需要先将图模式设置为 RESTORING 模式；当需要将备份的图合并到已存在的图中时，需要先将图模式设置为 MERGING 模式。

3.4 异步任务管理类，task-list、task-get、task-delete、task-cancel 和 task-clear

• task-list，列出某个图中的异步任务，可以根据任务的状态过滤
  • –status，选填项，指定要查看的任务的状态，即按状态过滤任务，合法值包括 [UNKNOWN, NEW, QUEUED, RESTORING, RUNNING, SUCCESS, CANCELLED, FAILED]（不区分大小写）
  • –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，要备份的顶点 label 或者边 label，仅在 –format 为 text 时生效；设置该项时，–huge-types 必须只包含一种类型，且该类型必须是 vertex 或者 edge，否则命令会失败
  • –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，‘schema’ 代表 4 种 schema 类型 [vertex_label, edge_label, property_key, index_label]
  • –log 或者 -l，指定日志目录，默认为 ./logs
  • –retry，指定失败重试次数，默认为 3
  • –thread-num 或者 -T，使用的线程数，默认为 Math.min(10, Math.max(4, CPUs / 2))
  • –split-size 或者 -s，指定在备份时对顶点或者边分块的大小，默认为 1048576，且不能小于 1048576（1M）
  • -D，用 -Dkey=value 的模式指定动态参数，用来备份数据到 HDFS 时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000

  当 –timeout 小于 120 秒时，backup（以及 migrate 中的备份步骤）会使用 120 秒

• 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，‘schema’ 代表 4 种 schema 类型 [vertex_label, edge_label, property_key, index_label]
  • –log 或者 -l，指定日志目录，默认为 ./logs
  • –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 命令恢复 restore 要求图处于 RESTORING 或 MERGING 模式（先用 graph-mode-set 设置），否则命令会失败

• 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，‘schema’ 代表 4 种 schema 类型 [vertex_label, edge_label, property_key, index_label]
  • –log 或者 -l，指定日志目录，默认为 ./logs
  • –retry，指定失败重试次数，默认为 3
  • –thread-num 或者 -T，使用的线程数，默认为 Math.min(10, Math.max(4, CPUs / 2))
  • –split-size 或者 -s，指定迁移过程中对源图进行备份时顶点或者边分块的大小，默认为 1048576，且不能小于 1048576（1M）
  • -D，用 -Dkey=value 的模式指定动态参数，用来在迁移图过程中需要备份数据到 HDFS 时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000
  • –graph-mode 或者 -m，将源图恢复到目标图时将目标图设置的模式，合法值包括 [RESTORING, MERGING]，默认为 RESTORING。迁移期间目标图会被切换到该模式，迁移结束后恢复为原来的模式
  • –keep-local-data，是否保留在迁移图的过程中产生的源图的备份，默认为 false，即默认迁移图结束后不保留产生的源图备份
• schedule-backup，周期性对图执行备份操作，并保留一定数目的最新备份（目前仅支持本地文件系统）
  • –directory 或者 -d，必填项，指定备份数据的目录
  • –backup-num，选填项，指定保存的最新的备份的数目，默认为 3
  • –interval，选填项，指定进行备份的周期，格式同 Linux crontab 格式，默认为 “0 0 * * *"（每天 00:00）

  schedule-backup 会添加一条 crontab 任务，定期执行 backup -t all 并写入 {directory}/{graph}/hugegraph-backup-{yyMMddHHmm}/，只保留最新的 –backup-num 份备份。相对路径的 –directory 会相对于 hugegraph-tools 的根目录解析，且 {directory}/{graph} 必须尚不存在

• 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 的目录，本地目录时，默认为’./{graphName}’，HDFS 时，默认为 ‘{fs.default.name}/{graphName}’
  • –log 或者 -l，指定日志目录，默认为 ./logs
  • –retry，指定失败重试次数，默认为 3
  • –thread-num 或者 -T，使用的线程数，默认为 Math.min(10, Math.max(4, CPUs / 2))
  • –split-size 或者 -s，指定在备份时对顶点或者边分块的大小，默认为 1048576，且不能小于 1048576（1M）
  • -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种类型；包含 ‘belong’ 时必须同时包含 ‘user’ 和 ‘group’，包含 ‘access’ 时必须同时包含 ‘group’ 和 ’target’
  • –directory，备份数据存储目录，本地目录时，默认为 ‘./auth-backup-restore’，HDFS 时，默认为 ‘{fs.default.name}/auth-backup-restore’（该选项没有 -d 短写）
  • –retry，指定失败重试次数，默认为 3
  • -D，用 -Dkey=value 的模式指定动态参数，用来备份数据到 HDFS 时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000
• auth-restore，从指定目录恢复认证数据
  • –types 或者 -t，要恢复的认证数据类型，逗号分隔，可选值为 ‘all’ 或者一个或多个 [user, group, target, belong, access] 的组合，‘all’ 代表全部5种类型；包含 ‘belong’ 时必须同时包含 ‘user’ 和 ‘group’，包含 ‘access’ 时必须同时包含 ‘group’ 和 ’target’
  • –directory，备份数据存储目录，本地目录时，默认为 ‘./auth-backup-restore’，HDFS 时，默认为 ‘{fs.default.name}/auth-backup-restore’（该选项没有 -d 短写）
  • –retry，指定失败重试次数，默认为 3
  • –strategy，冲突处理策略，可选值为 [stop, ignore]，默认为 stop。stop 表示遇到冲突时停止恢复，ignore 表示忽略冲突继续恢复
  • –init-password，恢复用户时设置的初始密码，当 –types 包含 user 时必填
  • -D，用 -Dkey=value 的模式指定动态参数，用来从 HDFS 恢复数据时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000

3.8 安装部署类

• deploy，一键下载、安装和启动 HugeGraph-Server 和 HugeGraph-Studio
  • -v，必填项，指定要安装的 HugeGraph-Server 和 HugeGraph-Studio 版本，必须是 bin/version-map.yaml 中列出的版本之一（0.6、0.7、0.8、0.9、0.10），脚本据此映射到对应的 server 和 studio 发布版本
  • -p，必填项，指定安装的 HugeGraph-Server 和 HugeGraph-Studio 目录
  • -u，选填项，指定下载 HugeGraph-Server 和 HugeGraph-Studio 压缩包的链接
• clear，清理 HugeGraph-Server 和 HugeGraph-Studio 目录和tar包（若对应的 server 或 studio 进程仍在运行则拒绝执行，删除每一项前都会提示确认）
  • -p，必填项，指定要清理的 HugeGraph-Server 和 HugeGraph-Studio 的目录
• start-all，一键启动 HugeGraph-Server 和 HugeGraph-Studio
  • -v，必填项，指定已安装的 HugeGraph-Server 和 HugeGraph-Studio 版本，取值同 deploy
  • -p，必填项，指定安装了 HugeGraph-Server 和 HugeGraph-Studio 的目录
• stop-all，一键关闭 HugeGraph-Server 和 HugeGraph-Studio

deploy、start-all、clear 和 stop-all 由 bin/hugegraph 直接转交给 bin/deploy.sh、bin/start-all.sh、bin/clear.sh 和 bin/stop-all.sh 执行，因此 3.2 中的全局变量和环境变量对它们不生效。

deploy命令中有可选参数 -u，提供时会使用指定的下载地址替代默认下载地址下载 tar 包，并且将地址写入~/hugegraph-download-url-prefix文件中；之后如果不指定地址时，会优先从~/hugegraph-download-url-prefix指定的地址下载 tar 包；如果 -u 和~/hugegraph-download-url-prefix都没有时，会从默认下载地址 https://github.com/hugegraph 进行下载

3.9 具体命令参数

各子命令的具体参数如下：

  1Usage: hugegraph [options] [command] [command options]
  2  Options:
  3    --graph
  4      Name of graph
  5      Default: hugegraph
  6    --password
  7      Password of user
  8    --throw-mode
  9      Whether the hugegraph-tools work to throw an exception
 10      Default: false
 11    --timeout
 12      Connection timeout
 13      Default: 30
 14    --trust-store-file
 15      The path of client truststore file used when https protocol is enabled
 16    --trust-store-password
 17      The password of the client truststore file used when the https protocol 
 18      is enabled
 19    --url
 20      The URL of HugeGraph-Server
 21      Default: http://127.0.0.1:8080
 22    --user
 23      Name of user
 24  Commands:
 25    graph-create      Create graph with config
 26      Usage: graph-create [options]
 27        Options:
 28          --file, -f
 29            Creating graph config file
 30          --name, -n
 31            The name of new created graph, default is g
 32            Default: g
 33
 34    graph-clone      Clone graph
 35      Usage: graph-clone [options]
 36        Options:
 37          --clone-graph-name
 38            The name of cloned graph, default is hugegraph
 39            Default: hugegraph
 40          --name, -n
 41            The name of new created graph, default is g
 42            Default: g
 43
 44    graph-list      List all graphs
 45      Usage: graph-list
 46
 47    graph-get      Get graph info
 48      Usage: graph-get
 49
 50    graph-clear      Clear graph schema and data
 51      Usage: graph-clear [options]
 52        Options:
 53        * --confirm-message, -c
 54            Confirm message of graph clear is "I'm sure to delete all data". 
 55            (Note: include "")
 56
 57    graph-drop      Drop graph
 58      Usage: graph-drop [options]
 59        Options:
 60        * --confirm-message, -c
 61            Confirm message of graph clear is "I'm sure to drop the graph". 
 62            (Note: include "")
 63
 64    graph-mode-set      Set graph mode
 65      Usage: graph-mode-set [options]
 66        Options:
 67        * --graph-mode, -m
 68            Graph mode, include: [NONE, RESTORING, MERGING]
 69            Possible Values: [NONE, RESTORING, MERGING, LOADING]
 70
 71    graph-mode-get      Get graph mode
 72      Usage: graph-mode-get
 73
 74    task-list      List tasks
 75      Usage: task-list [options]
 76        Options:
 77          --limit
 78            Limit number, no limit if not provided
 79            Default: -1
 80          --status
 81            Status of task
 82
 83    task-get      Get task info
 84      Usage: task-get [options]
 85        Options:
 86        * --task-id
 87            Task id
 88            Default: 0
 89
 90    task-delete      Delete task
 91      Usage: task-delete [options]
 92        Options:
 93        * --task-id
 94            Task id
 95            Default: 0
 96
 97    task-cancel      Cancel task
 98      Usage: task-cancel [options]
 99        Options:
100        * --task-id
101            Task id
102            Default: 0
103
104    task-clear      Clear completed tasks
105      Usage: task-clear [options]
106        Options:
107          --force
108            Force to clear all tasks, cancel all uncompleted tasks firstly, 
109            and delete all completed tasks
110            Default: false
111
112    gremlin-execute      Execute Gremlin statements
113      Usage: gremlin-execute [options]
114        Options:
115          --aliases, -a
116            Gremlin aliases, valid format is: 'key1=value1,key2=value2...'
117            Default: {}
118          --bindings, -b
119            Gremlin bindings, valid format is: 'key1=value1,key2=value2...'
120            Default: {}
121          --file, -f
122            Gremlin Script file to be executed, UTF-8 encoded, exclusive to 
123            --script 
124          --language, -l
125            Gremlin script language
126            Default: gremlin-groovy
127          --script, -s
128            Gremlin script to be executed, exclusive to --file
129
130    gremlin-schedule      Execute Gremlin statements as asynchronous job
131      Usage: gremlin-schedule [options]
132        Options:
133          --bindings, -b
134            Gremlin bindings, valid format is: 'key1=value1,key2=value2...'
135            Default: {}
136          --file, -f
137            Gremlin Script file to be executed, UTF-8 encoded, exclusive to 
138            --script 
139          --language, -l
140            Gremlin script language
141            Default: gremlin-groovy
142          --script, -s
143            Gremlin script to be executed, exclusive to --file
144
145    backup      Backup graph schema/data. If directory is on HDFS, use -D to 
146            set HDFS params. For example: 
147            -Dfs.default.name=hdfs://localhost:9000 
148      Usage: backup [options]
149        Options:
150          --all-properties
151            All properties to be backup flag
152            Default: false
153          --compress
154            compress flag
155            Default: true
156          --directory, -d
157            Directory of graph schema/data, default is './{graphname}' in 
158            local file system or '{fs.default.name}/{graphname}' in HDFS
159          --format
160            File format, valid is [json, text]
161            Default: json
162          --huge-types, -t
163            Type of schema/data. Concat with ',' if more than one. Other types 
164            include 'all' and 'schema'. 'all' means all vertices, edges and 
165            schema. In other words, 'all' equals with 'vertex, edge, 
166            vertex_label, edge_label, property_key, index_label'. 'schema' 
167            equals with 'vertex_label, edge_label, property_key, index_label'.
168            Default: [PROPERTY_KEY, VERTEX_LABEL, EDGE_LABEL, INDEX_LABEL, VERTEX, EDGE]
169          --label
170            Vertex label or edge label, only valid when type is vertex or edge
171          --log, -l
172            Directory of log
173            Default: ./logs
174          --properties
175            Vertex or edge properties to backup, only valid when type is 
176            vertex or edge
177            Default: []
178          --retry
179            Retry times, default is 3
180            Default: 3
181          --split-size, -s
182            Split size of shard
183            Default: 1048576
184          --thread-num, -T
185            Threads number to use, default is Math.min(10, Math.max(4, CPUs / 
186            2)) 
187            Default: 0
188          -D
189            HDFS config parameters
190            Syntax: -Dkey=value
191            Default: {}
192
193    schedule-backup      Schedule backup task
194      Usage: schedule-backup [options]
195        Options:
196          --backup-num
197            The number of latest backups to keep
198            Default: 3
199        * --directory, -d
200            The directory of backups stored
201          --interval
202            The interval of backup, format is: "a b c d e". 'a' means minute 
203            (0 - 59), 'b' means hour (0 - 23), 'c' means day of month (1 - 
204            31), 'd' means month (1 - 12), 'e' means day of week (0 - 6) 
205            (Sunday=0), "*" means all
206            Default: "0 0 * * *"
207
208    dump      Dump graph to files
209      Usage: dump [options]
210        Options:
211          --directory, -d
212            Directory of graph schema/data, default is './{graphname}' in 
213            local file system or '{fs.default.name}/{graphname}' in HDFS
214          --formatter, -f
215            Formatter to customize format of vertex/edge
216            Default: JsonFormatter
217          --log, -l
218            Directory of log
219            Default: ./logs
220          --retry
221            Retry times, default is 3
222            Default: 3
223          --split-size, -s
224            Split size of shard
225            Default: 1048576
226          --thread-num, -T
227            Threads number to use, default is Math.min(10, Math.max(4, CPUs / 
228            2)) 
229            Default: 0
230          -D
231            HDFS config parameters
232            Syntax: -Dkey=value
233            Default: {}
234
235    restore      Restore graph schema/data. If directory is on HDFS, use -D to 
236            set HDFS params if needed. For 
237            example:-Dfs.default.name=hdfs://localhost:9000 
238      Usage: restore [options]
239        Options:
240          --clean
241            Whether to remove the directory of graph data after restored
242            Default: false
243          --directory, -d
244            Directory of graph schema/data, default is './{graphname}' in 
245            local file system or '{fs.default.name}/{graphname}' in HDFS
246          --huge-types, -t
247            Type of schema/data. Concat with ',' if more than one. Other types 
248            include 'all' and 'schema'. 'all' means all vertices, edges and 
249            schema. In other words, 'all' equals with 'vertex, edge, 
250            vertex_label, edge_label, property_key, index_label'. 'schema' 
251            equals with 'vertex_label, edge_label, property_key, index_label'.
252            Default: [PROPERTY_KEY, VERTEX_LABEL, EDGE_LABEL, INDEX_LABEL, VERTEX, EDGE]
253          --log, -l
254            Directory of log
255            Default: ./logs
256          --retry
257            Retry times, default is 3
258            Default: 3
259          --thread-num, -T
260            Threads number to use, default is Math.min(10, Math.max(4, CPUs / 
261            2)) 
262            Default: 0
263          -D
264            HDFS config parameters
265            Syntax: -Dkey=value
266            Default: {}
267
268    migrate      Migrate graph
269      Usage: migrate [options]
270        Options:
271          --directory, -d
272            Directory of graph schema/data, default is './{graphname}' in 
273            local file system or '{fs.default.name}/{graphname}' in HDFS
274          --graph-mode, -m
275            Mode used when migrating to target graph, include: [RESTORING, 
276            MERGING] 
277            Default: RESTORING
278            Possible Values: [NONE, RESTORING, MERGING, LOADING]
279          --huge-types, -t
280            Type of schema/data. Concat with ',' if more than one. Other types 
281            include 'all' and 'schema'. 'all' means all vertices, edges and 
282            schema. In other words, 'all' equals with 'vertex, edge, 
283            vertex_label, edge_label, property_key, index_label'. 'schema' 
284            equals with 'vertex_label, edge_label, property_key, index_label'.
285            Default: [PROPERTY_KEY, VERTEX_LABEL, EDGE_LABEL, INDEX_LABEL, VERTEX, EDGE]
286          --keep-local-data
287            Whether to keep the local directory of graph data after restored
288            Default: false
289          --log, -l
290            Directory of log
291            Default: ./logs
292          --retry
293            Retry times, default is 3
294            Default: 3
295          --split-size, -s
296            Split size of shard
297            Default: 1048576
298          --target-graph
299            The name of target graph to migrate
300            Default: hugegraph
301          --target-password
302            The password of target graph to migrate
303          --target-timeout
304            The timeout to connect target graph to migrate
305            Default: 0
306          --target-trust-store-file
307            The trust store file of target graph to migrate
308          --target-trust-store-password
309            The trust store password of target graph to migrate
310          --target-url
311            The url of target graph to migrate
312            Default: http://127.0.0.1:8081
313          --target-user
314            The username of target graph to migrate
315          --thread-num, -T
316            Threads number to use, default is Math.min(10, Math.max(4, CPUs / 
317            2)) 
318            Default: 0
319          -D
320            HDFS config parameters
321            Syntax: -Dkey=value
322            Default: {}
323
324    deploy      Install HugeGraph-Server and HugeGraph-Studio
325      Usage: deploy [options]
326        Options:
327        * -p
328            Install path of HugeGraph-Server and HugeGraph-Studio
329          -u
330            Download url prefix path of HugeGraph-Server and HugeGraph-Studio
331        * -v
332            Version of HugeGraph-Server and HugeGraph-Studio
333
334    start-all      Start HugeGraph-Server and HugeGraph-Studio
335      Usage: start-all [options]
336        Options:
337        * -p
338            Install path of HugeGraph-Server and HugeGraph-Studio
339        * -v
340            Version of HugeGraph-Server and HugeGraph-Studio
341
342    clear      Clear HugeGraph-Server and HugeGraph-Studio
343      Usage: clear [options]
344        Options:
345        * -p
346            Install path of HugeGraph-Server and HugeGraph-Studio
347
348    stop-all      Stop HugeGraph-Server and HugeGraph-Studio
349      Usage: stop-all
350
351    auth-backup      null
352      Usage: auth-backup [options]
353        Options:
354          --directory
355            Directory of auth information, default is 
356            './{auth-backup-restore}' in local file system or 
357            '{fs.default.name}/{auth-backup-restore}' in HDFS
358          --retry
359            Retry times, default is 3
360            Default: 3
361          --types, -t
362            Type of auth data to restore and backup, concat with ',' if more 
363            than one. 'all' means all auth information. In other words, 'all' 
364            equals with 'user, group, target, belong, access'. In addition, 
365            'belong' or 'access' can not backup or restore alone, if type 
366            contains 'belong' then should contains 'user' and 'group'. If type 
367            contains 'access' then should contains 'group' and 'target'.
368            Default: [TARGET, GROUP, USER, ACCESS, BELONG]
369          -D
370            HDFS config parameters
371            Syntax: -Dkey=value
372            Default: {}
373
374    auth-restore      null
375      Usage: auth-restore [options]
376        Options:
377          --directory
378            Directory of auth information, default is 
379            './{auth-backup-restore}' in local file system or 
380            '{fs.default.name}/{auth-backup-restore}' in HDFS
381          --init-password
382            Init user password, if restore type include 'user', please specify 
383            the init-password of users.
384            Default: <empty string>
385          --retry
386            Retry times, default is 3
387            Default: 3
388          --strategy
389            The strategy needs to be chosen in the event of a conflict when 
390            restoring. Valid strategies include 'stop' and 'ignore', default 
391            is 'stop'. 'stop' means if there a conflict, stop restore. 
392            'ignore' means if there a conflict, ignore and continue to 
393            restore. 
394            Default: STOP
395            Possible Values: [STOP, IGNORE]
396          --types, -t
397            Type of auth data to restore and backup, concat with ',' if more 
398            than one. 'all' means all auth information. In other words, 'all' 
399            equals with 'user, group, target, belong, access'. In addition, 
400            'belong' or 'access' can not backup or restore alone, if type 
401            contains 'belong' then should contains 'user' and 'group'. If type 
402            contains 'access' then should contains 'group' and 'target'.
403            Default: [TARGET, GROUP, USER, ACCESS, BELONG]
404          -D
405            HDFS config parameters
406            Syntax: -Dkey=value
407            Default: {}
408
409    help      Print usage
410      Usage: help