HugeGraph ToolChain

• 1: HugeGraph-Hubble Quick Start
• 2: 图可视化
• 3: HugeGraph-Loader Quick Start
• 4: 图导入
  • 4.1: 使用 SeaTunnel Sink 导入图数据
• 5: Tools Quick Start
• 6: 图导出/迁移
  • 6.1: 使用 SeaTunnel Source 导出与迁移图数据
• 7: HugeGraph-Spark-Connector Quick Start

1 - HugeGraph-Hubble Quick Start

1 HugeGraph-Hubble 概述

⚠️ 安全提醒：Hubble 监听的是明文 HTTP 端口，请勿将其暴露在公网或不受信任的网络中；应在其前面终结 HTTPS，并使用 IP/端口白名单限制访问。Hubble 自身不保存账号库：当所连接的 HugeGraph Server 开启了鉴权时，Hubble 会显示登录页并把凭据转发给 Server；当 Server 允许匿名访问时，则没有登录环节，账号相关页面也会隐藏。

版本说明：本页对应 hugegraph-toolchain master。下文标注了依赖较新 Server、PD 或 Store 版本的功能，这些功能在旧版 Server 上不可用。

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

HugeGraph-Hubble 是 HugeGraph 的 Web 管理界面。它连接到一个 HugeGraph Server（直连，或在分布式集群中通过 PD 发现），管理图空间（GraphSpace）、图和 Schema，导入数据，执行 Gremlin 与 Cypher 查询以及内置图算法，并将结果图形化展示。

平台主要包括以下模块：

图概览

图概览列出图空间（PD 模式）和图，可以创建、克隆和清空图，加载 Demo 图，打开包含统计信息与 Schema 的图详情页，并跳转到查询工作台。

元数据建模

元数据建模用于管理单个图的 PropertyKey、VertexLabel、EdgeLabel 和 IndexLabel，提供列表与图两种视图。Schema 模板按图空间保存可复用的 Groovy Schema，可在创建图时直接套用。

数据导入

数据导入页面适合小规模试用。大批量或生产导入请使用 HugeGraph Loader。

数据源支持 FILE、HDFS、JDBC 和 KAFKA 四种类型。导入任务分四步配置，可以执行一次、按 cron 周期执行，或对 Kafka 源持续实时执行。

图查询

图查询可以按立即查询或异步任务两种模式执行 Gremlin 与 Cypher 语句，并以图（2D 或 3D）、表格或 JSON 展示结果，同时保存执行记录与收藏语句。

内置图算法

内置图算法为 Server 的 OLTP traverser 接口（交互式探索）以及 OLAP 任务（通过 HugeGraph Computer 或 Vermeer 进行集群批量计算）提供参数表单。

异步任务

异步任务列出后台任务，包括 Gremlin 与 Cypher 任务、算法任务、删除元数据、创建与重建索引、Vermeer 图加载与图计算任务，并支持查看详情、取消和删除。

系统与运维

系统与运维包含个人中心、带图空间权限预设的账号管理，以及 PD 模式下的集群概览与节点详情。

1.1 版本兼容性

Hubble 会自动探测所连接 Server 的鉴权模式与能力，自身没有单独的鉴权开关。支持的组合如下：

分布式集群中请使用版本号一致的 Server、PD 和 Store。

2 部署

有三种方式可以部署hugegraph-hubble

• 使用 docker (便于测试)
• 下载 toolchain 二进制包
• 源码编译

Hubble 运行在 Java 11 上：后端以 java.version=11 编译，Docker 镜像基于 eclipse-temurin:11-jre。bin/start-hubble.sh 只检查 PATH 中是否存在 java，因此请自行确认选用的是正确的 JDK。

2.1 使用 Docker (便于测试)

特别注意：Hubble 已不再在页面上填写 Server 的主机名和端口。Server 地址来自 conf/hugegraph-hubble.properties：pd.enabled=false 时使用 server.direct_url，pd.enabled=true 时通过 pd.peers 由 PD 发现。容器内的 127.0.0.1 指向 hubble 容器自身，因此打包默认值 server.direct_url=http://127.0.0.1:8080 无法访问到另一个容器里的 Server。

若 hubble 和 server 在同一 docker 网络下，推荐直接使用container_name (如下例的 server) 作为主机名。或者也可以使用 宿主机 IP 作为主机名，此时端口号为宿主机给 server 配置的端口

镜像会把打包产物复制到 /hubble，把 /hubble/conf/hugegraph-hubble.properties 中的 server.host 改写为 0.0.0.0、清空 dashboard.address，暴露 8088 端口，并以 ./bin/start-hubble.sh -f 前台方式启动。

先准备一份指向你的 Server、并让容器监听所有网卡的 hugegraph-hubble.properties：

server.host=0.0.0.0
server.port=8088
pd.enabled=false
server.direct_url=http://server:8080

然后把该文件挂载覆盖打包配置来启动 hubble：

docker run -itd --name=hubble -p 8088:8088 \
  -v "$PWD/hugegraph-hubble.properties:/hubble/conf/hugegraph-hubble.properties" \
  hugegraph/hubble:1.7.0

或者使用 docker-compose 启动 hubble，另外如果 hubble 和 server 在同一个 docker 网络下，可以使用 server 的 container_name 进行访问，而不需要宿主机的 ip

使用docker-compose up -d，docker-compose.yml如下：

version: '3'
services:
  server:
    image: hugegraph/hugegraph:1.7.0
    container_name: server
    environment:
      - PASSWORD=xxx
    ports:
      - 8080:8080

  hubble:
    image: hugegraph/hubble:1.7.0
    container_name: hubble
    ports:
      - 8088:8088
    volumes:
      - ./hugegraph-hubble.properties:/hubble/conf/hugegraph-hubble.properties

注意：

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

2. 生产环境推荐使用 release tag(如 1.7.0) 稳定版。使用 latest tag 默认对应 master 最新代码。

2.2 下载 toolchain 二进制包

hubble项目在toolchain项目中，首先下载toolchain的 tar 包

export VERSION=1.7.0
export ARCHIVE="apache-hugegraph-toolchain-incubating-${VERSION}"
wget "https://downloads.apache.org/hugegraph/${VERSION}/${ARCHIVE}.tar.gz"
tar -xvf "${ARCHIVE}.tar.gz"
cd "${ARCHIVE}/apache-hugegraph-hubble-incubating-${VERSION}"

先修改 conf/hugegraph-hubble.properties，把 Server 地址配置正确，然后运行hubble

bin/start-hubble.sh

start-hubble.sh 支持以下参数：

脚本以 -Xms512m -Dfile.encoding=UTF-8 -Dhubble.home.path=<安装目录> 启动 JVM，把 PID 写入 bin/pid，日志输出到 logs/hugegraph-hubble.log，并最多等待 30 秒直到 http://<server.host>:<server.port>/about 有响应后才返回。

打包默认值为 server.host=localhost，即在修改之前只接受本机回环访问。启动完成后访问 http://<host>:8088。

停止服务时执行 bin/stop-hubble.sh：它先发送 SIGTERM，让关闭钩子暂停正在运行的导入任务并干净地关闭内置 H2 数据库；只有在 STOP_TIMEOUT 秒（环境变量，默认 30）后进程仍然存活时，才会升级为 SIGKILL。

2.3 源码编译

Hubble 的构建由 hugegraph-hubble/hubble-dist/pom.xml 中的 frontend-maven-plugin 安装 Node.js v18.20.8 和 Yarn v1.22.21，无需预先安装这两个工具。此外需要 JDK 11 和 Maven。

下载 toolchain 源码包

git clone https://github.com/apache/hugegraph-toolchain.git

编译hubble, 它依赖 loader 和 client, 编译时需提前构建这些依赖 (后续可跳)

cd hugegraph-toolchain
python -m pip install -r hugegraph-hubble/hubble-dist/assembly/travis/requirements.txt
mvn install -pl hugegraph-client,hugegraph-loader -am -Dmaven.javadoc.skip=true -DskipTests -ntp

cd hugegraph-hubble
mvn -e package -Dmaven.javadoc.skip=true -Dmaven.test.skip=true -ntp
cd apache-hugegraph-hubble-*

启动hubble

bin/start-hubble.sh -d

前端开发时可在 hubble-fe 目录下执行 yarn dev。后端 POM 未配置 spring-boot:run，请改为从 hubble-be/target/classes 启动 org.apache.hugegraph.HugeGraphHubble，并用 -Dhubble.home.path 指向一个可写目录。

3 平台使用流程

首页把各模块归纳为三条主线：图概览、图导入和图查询，同时显示当前运行在 PD / 集群模式还是 non-PD 单机模式。平台的模块使用流程如下：

4 平台使用说明

4.1 图管理

在 PD 模式下，【图空间管理】列出集群中的所有图空间，并可创建或编辑图空间，包括别名、可选的 Kubernetes 命名空间与计算任务，以及资源上限。在 non-PD 单机模式下只有一个名为 DEFAULT 的图空间，图空间列表会被跳过。

4.1.1 图创建

图管理模块下，点击【新建图】，填写图名称、可选的别名、可选的 Schema 模板和示例数据。图名称在其所属图空间内唯一，创建后不可修改。

创建图填写内容如下：

注意：Server 连接不在此页面配置，而是来自 conf/hugegraph-hubble.properties，通过 server.direct_url 或 PD 发现获得，Docker 下的主机名规则见 2.1 节。只有当所连接的 Server 提供建图能力（REST API 0.67 及以上）时才会显示新建图入口，旧版 Server 上图列表为只读。

4.1.2 图访问

实现图空间的信息访问，进入后，可进行图的多维查询分析、元数据管理、数据导入、算法分析等操作。【进入图分析平台】打开查询工作台，【元数据配置】打开 Schema 页面，图详情页展示顶点/边统计信息和 Schema。

4.1.3 图管理

1. 图列表提供卡片视图和列表视图，搜索按图名称匹配。
2. 单图操作包括：查看 schema（可【导出 Groovy Schema】）、元数据配置、克隆图（仅 Schema，或 Schema 与数据）、清空 Schema 与数据、删除，以及 PD 模式下的设为默认。
3. 【示例数据与资源】可在当前图中构建 Demo 图：红楼梦 Demo 图、人物与软件 Demo 图、迷你电影 Rank Demo。这些 Demo 只补齐缺失的 Schema 和元素，不会清空已有数据。

4.2 元数据建模（列表 + 图模式）

4.2.1 模块入口

从图列表进入【元数据配置】，或直接访问图的元数据页面 /graphspace/<graphspace>/graph/<graph>/meta。页面包含属性、顶点类型、边类型、顶点索引、边索引五个标签页，并可在列表视图和图视图之间切换。

4.2.2 属性类型

4.2.2.1 创建

1. 填写或选择属性名称、数据类型、基数，完成属性的创建。
2. 创建的属性可作为顶点类型和边类型的属性。

列表模式：

图模式：

4.2.2.2 管理

1. 在属性列表中可进行单条删除或批量删除操作，已被顶点类型或边类型使用的属性无法删除。
2. 删除元数据会以异步任务方式执行，可在异步任务中查看进度。

4.2.3 顶点类型

4.2.3.1 创建

1. 填写或选择顶点类型名称、ID 策略、关联属性、主键属性，顶点样式、查询结果中顶点下方展示的内容，以及索引的信息：包括是否创建类型索引，及属性索引的具体内容，完成顶点类型的创建。

列表模式：

图模式：

4.2.3.2 管理

1. 可进行编辑操作，顶点样式、关联属性、顶点展示内容、属性索引可编辑，其余不可编辑。图模式下双击顶点类型即可编辑。

2. 可进行单条删除或批量删除操作。

4.2.4 边类型

4.2.4.1 创建

1. 填写或选择边类型名称、类型（普通类型、父边类型或子边类型，用于边类型的层级关系）、起点类型、终点类型、关联属性、是否允许多次连接、边样式、查询结果中边下方展示的内容，以及索引的信息：包括是否创建类型索引，及属性索引的具体内容，完成边类型的创建。

列表模式：

图模式：

4.2.4.2 管理

1. 可进行编辑操作，边样式、关联属性、边展示内容、属性索引可编辑，其余不可编辑，同顶点类型。
2. 可进行单条删除或批量删除操作。

4.2.5 索引类型

展示顶点类型和边类型的顶点索引和边索引，支持二级索引、范围索引、全文索引和唯一索引。

4.2.6 Schema 模板

【Schema 模板】（/graphspace/<graphspace>/schema）按图空间维护一份可复用的模板库。示例模板由 Hubble 内置，可以使用、移除和恢复，在保存之前不会写入 Server；用户模板以 Groovy Schema 形式保存在 Server 上，可以创建、编辑和删除。创建图时可以选择已有模板，使其 Schema 立即生效。

4.3 数据导入

注意：目前推荐使用 hugegraph-loader 进行正式数据导入，hubble 内置的导入用来做测试和简单上手

数据导入的使用流程如下：

4.3.1 模块入口

左侧导航「图导入」下的【数据源管理】和【数据导入】：

4.3.2 数据源

1. 【数据源管理】用于登记导入任务的读取来源，支持四种类型：FILE（本地上传）、HDFS、Kafka 和 JDBC。
2. FILE 类型需要上传需要构图的文件，可接受的格式由 upload_file.format_list 决定，默认为 csv 和 txt。
3. 单文件与总大小上限默认分别为 1 GB 和 10 GB，未完成的上传分片会在 upload_file.max_uploading_time（默认 12 小时）后被清理。

4.3.3 创建任务

1. 【数据导入】>【创建任务】分四步配置：输入基础信息、选择源端字段、选择映射字段、输入调度信息。
2. 基础信息包括任务名称（1 到 48 个中文、字母、数字或 _）、目标图空间与图、源端类型和数据源。
3. 可创建多个导入任务，并行导入。

4.3.4 设置数据映射

1. 对选定的数据源设置数据映射，包括文件设置和类型设置

2. 文件设置：勾选或填写是否包含表头、分隔符、编码格式等源端本身的设置内容，均设置默认值，无需手动填写

3. 类型设置：

   1. 顶点映射和边映射：

      【顶点类型】 ：选择顶点类型，并为其 ID 映射源端中的列数据；

      【边类型】：选择边类型，为其起点类型和终点类型的 ID 列映射源端的列数据；

   2. 映射设置：为选定的顶点类型的属性映射源端中的列数据，此处，若属性名称与文件的表头名称一致，可自动匹配映射属性，无需手动填选

   3. 完成设置后，显示设置列表，方可进行下一步操作，支持映射的新增、编辑、删除操作

设置映射的填写内容：

映射列表：

4.3.5 导入数据

最后一步选择任务的执行方式：执行一次表示一次性导入，周期执行使用 Quartz cron 表达式（例如 0 0/5 * * * ?），实时执行用于 Kafka 数据源。

1. 导入设置

• 导入设置参数项如下图所示，均设置默认值，无需手动填写

2. 导入详情

• 在任务列表中运行任务即可开始导入，也可在同一列表中暂停、编辑或删除任务
• 任务的执行历史提供每次执行的执行实例 ID、导入记录数、平均速率（条/秒）、导入耗时和状态
• 若导入失败，可查看具体原因

4.4 图查询

4.4.1 模块入口

左侧导航「图查询」下的【GQL 图遍历】：

4.4.2 多图切换

顶部栏承载当前图空间和图，可在不离开页面的情况下灵活切换多图的操作空间

4.4.3 图分析与处理

HugeGraph 支持 Apache TinkerPop3 的图遍历查询语言 Gremlin，Gremlin 是一种通用的图数据库查询语言，通过输入 Gremlin 语句，点击执行，即可执行图数据的查询分析操作，并可实现顶点/边的创建及删除、顶点/边的属性修改等。当所连接的 Server 支持 Cypher 时，Gremlin 旁边会出现 Cypher 页签。Text2GQL 页签仅为界面预览，并未接入任何模型或查询服务，其中输入的内容不会被发送或执行。

每条语句可以按两种模式执行：立即查询直接返回结果，适合 30 秒内可完成的小规模分析；异步执行则提交一个任务，进度和结果在异步任务中查看。Ctrl/Command + Enter 可执行当前语句。

查询后，下方为图结果展示区域，提供 3 种图结果展示方式，分别为：【图模式】、【表格模式】、【Json 模式】。图画布支持 2D 与 3D 渲染。

⚠️ SEC 提醒：Hubble 允许在网页端直接输入并执行 Gremlin 原生查询语句，这赋予了使用者较高的操作权限。请避免将 Hubble 服务暴露在公网环境，建议在使用时确保图数据库服务端已开启 鉴权体系 (Auth) 并配合 IP 白名单进行严格的权限控制，防止未授权访问或恶意代码执行风险。

支持缩放、居中、全屏、布局与样式配置、图例、缩略图、撤销与重做、导出等操作。画布可导出为 JSON、CSV 或图片，导出的画布也可以再次导入。

【图模式】

【表格模式】

【Json 模式】

4.4.4 数据详情

点击顶点/边实体，可查看顶点/边的数据详情，包括：顶点/边类型，顶点 ID，属性及对应值，拓展图的信息展示维度，提高易用性。

4.4.5 图结果的多维路径查询

除了全局的查询外，可针对查询结果中的顶点进行深度定制化查询以及隐藏操作，实现图结果的定制化挖掘。

右击顶点，出现顶点的菜单入口，可进行展示、查询、隐藏等操作。

• 展开：点击后，展示与选中点关联的顶点。
• 查询：通过选择与选中点关联的边类型及边方向，在此条件下，再选择其属性及相应筛选规则，可实现定制化的路径展示。
• 隐藏：点击后，隐藏选中点及与之关联的边。

双击顶点，也可展示与选中点关联的顶点。

4.4.6 新增顶点/边

4.4.6.1 新增顶点

在图区可通过两个入口，动态新增顶点，如下：

1. 点击图区面板，出现添加顶点入口
2. 点击右上角的操作栏中的首个图标

通过选择或填写顶点类型、ID 值、属性信息，完成顶点的增加。

入口如下：

添加顶点内容如下：

4.4.6.2 新增边

右击图结果中的顶点，可增加该点的出边或者入边。

4.4.7 执行记录与收藏的查询

1. 图区下方记载每次查询记录，包括：查询时间、执行类型、内容、状态、耗时、以及【收藏】和【加载】操作，实现图执行的全方位记录，有迹可循，并可对执行内容快速加载复用
2. 提供语句的收藏功能，可对常用语句进行收藏操作，方便高频语句快速调用

4.5 异步任务

4.5.1 模块入口

左侧导航「图查询」下的【异步任务】：

4.5.2 任务管理

1. 提供异步任务的统一的管理与结果查看，任务类型包括：

• gremlin：Gremlin 任务
• cypher：Cypher 任务
• computer-dis：算法任务
• remove_schema：删除元数据
• create_index：创建索引
• rebuild_index：重建索引
• vermeer-task:load：Vermeer 图加载任务
• vermeer-task:compute：Vermeer 图计算任务

2. 列表显示当前图的异步任务信息，包括：任务 ID，任务名称，任务类型，创建时间，耗时，状态，操作，实现对异步任务的管理。列表每 5 秒自动刷新一次。
3. 支持对任务类型和状态进行筛选
4. 支持搜索任务 ID 和任务名称
5. 运行中的任务可以取消，异步任务可进行删除或批量删除操作

4.5.3 Gremlin 异步任务

1.创建任务

• 图查询模块支持两种执行方式：立即查询和异步任务；若用户切换到异步方式，点击执行后，在异步任务中心会建立一条异步任务；Cypher 语句同理会建立一条 Cypher 任务； 2.任务提交
• 任务提交成功后，图区部分返回提交结果和任务 ID 3.任务详情
• 提供【查看】入口，可跳转到任务详情查看当前任务具体执行情况跳转到任务中心后，直接显示当前执行的任务行

点击查看入口，跳转到任务管理列表，如下：

4.查看结果

• 结果通过 json 形式展示，较长的结果可以就地展开

4.5.4 算法任务

从【内置图算法】提交的批量算法会在这里以算法任务的形式出现，Vermeer 的图加载与图计算任务同理。可在列表中通过 ID 找到相应任务，打开后查看进度与结果等。算法表单本身见 4.6 节。

4.5.5 删除元数据、重建索引

1.创建任务

• 在元数据建模模块中，删除元数据时，可建立删除元数据的异步任务

• 在编辑已有的顶点/边类型操作中，新增索引时，可建立创建索引的异步任务

2.任务详情

• 确认/保存后，可跳转到任务中心查看当前任务的详情

4.6 内置图算法

「图查询」下的【内置图算法】为 Server 提供的算法给出参数表单，并按用途分组：探索邻居、寻找路径与连接、比较与排序、度量重要性、发现社区、分析图结构。每个算法都提供指向官方 API 文档的链接。

支持两种执行方式：

• 交互式探索调用 Server 的 OLTP traverser 接口并直接返回结果，覆盖 K-out 与 K-neighbor，单源、带权和多点形式的最短路径，路径与全部路径，定制化路径与模板路径，环与射线，交点与定制化交点，共同邻居，Jaccard 相似度，Fusiform 相似度，Adamic-Adar，资源分配，Egonet，以及 rank 与 neighbor rank 接口。
• 集群批量计算提交一个覆盖全图的异步任务，结果在异步任务中查看，覆盖 PageRank 与个性化 PageRank，度中心性、接近中心性与介数中心性，K-core，弱连通分量，标签传播，Louvain，三角形计数，聚类系数，环检测，子图匹配与 Links；在提供 Vermeer 的部署中还有对应的 Vermeer 版本。

批量算法需要 HugeGraph Computer 环境，部署要求时还包括 Kubernetes。当无法访问 Computer 时，页面会直接提示而不会提交任务。

4.7 登录与账号管理

当所连接的 Server 开启了鉴权时，Hubble 会打开 /login 登录页。请使用 HugeGraph Server 账号登录：Hubble 会把凭据转发给 Server，并在浏览器会话中保存返回的 token，自身不存储任何账号。登录尝试受限流保护，同一账号与地址连续失败三次之后，后续尝试会开始退避，初始 5 秒并逐次翻倍，最长 600 秒。当 Server 允许匿名访问时，/login 会重定向到首页，个人中心和账号管理页面也会隐藏。

【个人中心】展示账号信息并可修改密码。【账号管理】面向具备账号管理或图空间成员管理能力的账号，可创建账号并分配四种权限预设之一：超级管理员、GraphSpace 只读、GraphSpace 读写、GraphSpace 管理员。界面上不再暴露底层的 role、target、access、belong 记录。

4.8 集群运维

在 PD 模式下，【系统与运维】会为具备相应能力的账号提供【集群概览】和【节点详情】。集群概览展示拓扑、各层级的节点状态，以及在线 Store 数、PD Leader、容量、数据量、图数、分区数、副本数等集群概况。节点详情列出所有发现到的节点，支持按类型和状态筛选，并可打开单个节点查看指标、Leader 角色和 Raft 分片。节点详情在单机模式下同样可用，集群概览则需要 PD。

导航页还可以通过 dashboard.address 链接一个可选的外部监控面板。它是独立的监控入口，不配置也不会影响集群概览和节点详情。

5 配置说明

HugeGraph-Hubble 可以通过 conf/hugegraph-hubble.properties 文件进行配置。

5.1 服务配置

5.2 Server 与 PD

5.3 Gremlin 查询限制

这些设置控制查询结果限制，防止内存问题：

5.4 文件上传

以下配置项不在打包的配置文件中，如需覆盖默认值请自行添加。

5.5 集群运维

以下配置项用于集群概览和节点详情页面。

operations.store.allowed_targets 的默认值仅适用于本地测试。生产部署必须显式列出每一个受信任的 Store 协议、主机和端口，服务发现不会向该白名单追加来源。HTTPS 来源会保留其配置的主机名用于 TLS SNI 与证书校验。PD 和 Store 的密码请通过受保护的部署配置提供，不要写入打包的配置文件。

2 - 图可视化

需要在浏览器中查看图、执行 Gremlin 或管理图连接时，使用 Hubble。Hubble 提供图数据、Schema 和任务的可视化界面。

• 使用 Hubble 实现图可视化

3 - HugeGraph-Loader Quick Start

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 Quick Start

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

2 获取 HugeGraph-Loader

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

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

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

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

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

version: '3'

services:
  server:
    image: hugegraph/hugegraph:1.7.0
    container_name: server
    environment:
      - PASSWORD=xxx
    ports:
      - 8080:8080

  hubble:
    image: hugegraph/hubble:1.7.0
    container_name: hubble
    ports:
      - 8088:8088

  loader:
    image: hugegraph/loader:1.7.0
    container_name: loader
    # mount your own data here
    # volumes:
      # - /path/to/data/file:/loader/file

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

注意：

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

2. 推荐使用 release tag (如 1.7.0) 以获取稳定版。使用 latest tag 可以使用开发中的最新功能。

2.2 下载已编译的压缩包

下载最新版本的 HugeGraph-Toolchain Release 包，里面包含了 loader + tool + hubble 全套工具，如果你已经下载，可跳过重复步骤

export VERSION=1.7.0
export ARCHIVE="apache-hugegraph-toolchain-incubating-${VERSION}"
wget "https://downloads.apache.org/hugegraph/${VERSION}/${ARCHIVE}.tar.gz"
tar zxf "${ARCHIVE}.tar.gz"

2.3 克隆源码编译安装

克隆最新版本的 HugeGraph-Loader 源码包：

# 1. get from github
git clone https://github.com/apache/hugegraph-toolchain.git

# 2. 下载发布版源码包
export VERSION=1.7.0
export ARCHIVE="apache-hugegraph-toolchain-incubating-${VERSION}"
wget "https://downloads.apache.org/hugegraph/${VERSION}/${ARCHIVE}-src.tar.gz"

mvn install:install-file -Dfile=./ojdbc8.jar -DgroupId=com.oracle -DartifactId=ojdbc8 -Dversion=12.2.0.1 -Dpackaging=jar

编译生成 tar 包：

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

3 使用流程

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

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

3.1 编写图模型

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

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

示例图模型

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

// 创建一些属性
schema.propertyKey("name").asText().ifNotExist().create();
schema.propertyKey("age").asInt().ifNotExist().create();
schema.propertyKey("city").asText().ifNotExist().create();
schema.propertyKey("date").asText().ifNotExist().create();
schema.propertyKey("price").asDouble().ifNotExist().create();

// 创建 person 顶点类型，其拥有三个属性：name, age, city，主键是 name
schema.vertexLabel("person").properties("name", "age", "city").primaryKeys("name").ifNotExist().create();
// 创建 software 顶点类型，其拥有两个属性：name, price，主键是 name
schema.vertexLabel("software").properties("name", "price").primaryKeys("name").ifNotExist().create();

// 创建 knows 边类型，这类边是从 person 指向 person 的
schema.edgeLabel("knows").sourceLabel("person").targetLabel("person").ifNotExist().create();
// 创建 created 边类型，这类边是从 person 指向 software 的
schema.edgeLabel("created").sourceLabel("person").targetLabel("software").ifNotExist().create();

关于 schema 的详细说明请参考 hugegraph-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 或属性；

示例如下：

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

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

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

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

{"source_name": "marko", "target_name": "vadas", "date": "20160110", "weight": 0.5}
{"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

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

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

// created 表结构
id | 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）

Tom,48,Beijing
Jerry,36,Shanghai

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

name,price
Photoshop,999
Office,388

3.2.2.2 边数据

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

• knows 边数据

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

• created 边数据

{"source_name": "Tom", "target_name": "Photoshop"}
{"source_name": "Tom", "target_name": "Office"}
{"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 版本的。

{
  "version": "2.0",
  "structs": [
    {
      "id": "1",
      "input": {
      },
      "vertices": [
        {},
        {}
      ],
      "edges": [
        {},
        {}
      ]
    }
  ]
}

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

{
  "version": "2.0",
  "structs": [
    {
      "id": "1",
      "skip": false,
      "input": {
        "type": "FILE",
        "path": "vertex_person.csv",
        "file_filter": {
          "extensions": [
            "*"
          ]
        },
        "format": "CSV",
        "delimiter": ",",
        "date_format": "yyyy-MM-dd HH:mm:ss",
        "time_zone": "GMT+8",
        "skipped_line": {
          "regex": "(^#|^//).*|"
        },
        "compression": "NONE",
        "header": [
          "name",
          "age",
          "city"
        ],
        "charset": "UTF-8",
        "list_format": {
          "start_symbol": "[",
          "elem_delimiter": "|",
          "end_symbol": "]"
        }
      },
      "vertices": [
        {
          "label": "person",
          "skip": false,
          "id": null,
          "unfold": false,
          "field_mapping": {},
          "value_mapping": {},
          "selected": [],
          "ignored": [],
          "null_values": [
            ""
          ],
          "update_strategies": {}
        }
      ],
      "edges": []
    },
    {
      "id": "2",
      "skip": false,
      "input": {
        "type": "FILE",
        "path": "vertex_software.csv",
        "file_filter": {
          "extensions": [
            "*"
          ]
        },
        "format": "CSV",
        "delimiter": ",",
        "date_format": "yyyy-MM-dd HH:mm:ss",
        "time_zone": "GMT+8",
        "skipped_line": {
          "regex": "(^#|^//).*|"
        },
        "compression": "NONE",
        "header": null,
        "charset": "UTF-8",
        "list_format": {
          "start_symbol": "",
          "elem_delimiter": ",",
          "end_symbol": ""
        }
      },
      "vertices": [
        {
          "label": "software",
          "skip": false,
          "id": null,
          "unfold": false,
          "field_mapping": {},
          "value_mapping": {},
          "selected": [],
          "ignored": [],
          "null_values": [
            ""
          ],
          "update_strategies": {}
        }
      ],
      "edges": []
    },
    {
      "id": "3",
      "skip": false,
      "input": {
        "type": "FILE",
        "path": "edge_knows.json",
        "file_filter": {
          "extensions": [
            "*"
          ]
        },
        "format": "JSON",
        "delimiter": null,
        "date_format": "yyyy-MM-dd HH:mm:ss",
        "time_zone": "GMT+8",
        "skipped_line": {
          "regex": "(^#|^//).*|"
        },
        "compression": "NONE",
        "header": null,
        "charset": "UTF-8",
        "list_format": null
      },
      "vertices": [],
      "edges": [
        {
          "label": "knows",
          "skip": false,
          "source": [
            "source_name"
          ],
          "unfold_source": false,
          "target": [
            "target_name"
          ],
          "unfold_target": false,
          "field_mapping": {
            "source_name": "name",
            "target_name": "name"
          },
          "value_mapping": {},
          "selected": [],
          "ignored": [],
          "null_values": [
            ""
          ],
          "update_strategies": {}
        }
      ]
    },
    {
      "id": "4",
      "skip": false,
      "input": {
        "type": "FILE",
        "path": "edge_created.json",
        "file_filter": {
          "extensions": [
            "*"
          ]
        },
        "format": "JSON",
        "delimiter": null,
        "date_format": "yyyy-MM-dd HH:mm:ss",
        "time_zone": "GMT+8",
        "skipped_line": {
          "regex": "(^#|^//).*|"
        },
        "compression": "NONE",
        "header": null,
        "charset": "UTF-8",
        "list_format": null
      },
      "vertices": [],
      "edges": [
        {
          "label": "created",
          "skip": false,
          "source": [
            "source_name"
          ],
          "unfold_source": false,
          "target": [
            "target_name"
          ],
          "unfold_target": false,
          "field_mapping": {
            "source_name": "name",
            "target_name": "name"
          },
          "value_mapping": {},
          "selected": [],
          "ignored": [],
          "null_values": [
            ""
          ],
          "update_strategies": {}
        }
      ]
    }
  ]
}

{
  "vertices": [
    {
      "label": "person",
      "input": {
        "type": "file",
        "path": "vertex_person.csv",
        "format": "CSV",
        "header": ["name", "age", "city"],
        "charset": "UTF-8"
      }
    },
    {
      "label": "software",
      "input": {
        "type": "file",
        "path": "vertex_software.csv",
        "format": "CSV"
      }
    }
  ],
  "edges": [
    {
      "label": "knows",
      "source": ["source_name"],
      "target": ["target_name"],
      "input": {
        "type": "file",
        "path": "edge_knows.json",
        "format": "JSON"
      },
      "field_mapping": {
        "source_name": "name",
        "target_name": "name"
      }
    },
    {
      "label": "created",
      "source": ["source_name"],
      "target": ["target_name"],
      "input": {
        "type": "file",
        "path": "edge_created.json",
        "format": "JSON"
      },
      "field_mapping": {
        "source_name": "name",
        "target_name": "name"
      }
    }
  ]
}

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

bin/mapping-convert.sh struct.json

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

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

bin/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: 本地文件或目录的路径，绝对路径或相对于映射文件的相对路径，建议使用绝对路径，必填；
  • file_filter: 从path中筛选复合条件的文件，复合结构，目前只支持配置扩展名，用子节点extensions表示，默认为”*"，表示保留所有文件；
  • format: 本地文件的格式，可选值为 CSV、TEXT 及 JSON，必须大写，默认为 CSV，选填；
  • header: 文件各列的列名，如不指定则会以数据文件第一行作为 header；当文件本身有标题且又指定了 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：是否从 topic 最早的 offset 开始读取（auto.offset.reset=earliest），否则从最新 offset 开始，默认为 false，选填；
• 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：想跳过的行，复合结构，目前只能配置要跳过的行的正则表达式，用子节点 regex 描述，默认不跳过任何行，选填；
• 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

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

// JSON 文件中以如下方式指定更新策略
{
  "vertices": [
    {
      "label": "person",
      "update_strategies": {
        "age": "SMALLER",
        "set": "UNION"
      },
      "input": {
        "type": "file",
        "path": "vertex_person.txt",
        "format": "TEXT",
        "header": ["name", "age", "set"]
      }
    }
  ]
}

// 1.写入一行带 OVERRIDE 更新策略的数据 (这里 null 代表空)
'a b null null'

// 2.再写一行
'null null c d'

// 3.最后可以得到
'a b c d'   

// 如果没有更新策略，则会得到
'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 参数说明

参数少于三个时 loader 会直接打印用法并退出，因此只传 -f struct.json 是不够的。

3.4.2 断点续导模式

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

用户设置命令行参数 –incremental-mode 为 true 即打开了断点续导模式。断点续导的关键在于进度文件，导入进程退出的时候，会把退出时刻的导入进度 记录到进度文件中，进度文件位于 ${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 是否打开无关，每次导入结束都会生成一个进度文件。

如果数据文件格式都是合法的，是用户自己停止（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 并传入参数

bin/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 配置。

4 完整示例

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

4.1 准备数据

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

marko,29,Beijing
vadas,27,Hongkong
josh,32,Beijing
peter,35,Shanghai
"li,nary",26,"Wu,han"
tom,null,NULL

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

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

边文件：example/file/edge_knows.json

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

边文件：example/file/edge_created.json

{"aname": "marko", "bname": "lop", "date": "20171210", "weight": 0.4}
{"aname": "josh", "bname": "lop", "date": "20091111", "weight": 0.4}
{"aname": "josh", "bname": "ripple", "date": "20171210", "weight": 1.0}
{"aname": "peter", "bname": "lop", "date": "20170324", "weight": 0.2}

4.2 编写 schema

schema.propertyKey("name").asText().ifNotExist().create();
schema.propertyKey("age").asInt().ifNotExist().create();
schema.propertyKey("city").asText().ifNotExist().create();
schema.propertyKey("weight").asDouble().ifNotExist().create();
schema.propertyKey("lang").asText().ifNotExist().create();
schema.propertyKey("date").asText().ifNotExist().create();
schema.propertyKey("price").asDouble().ifNotExist().create();

schema.vertexLabel("person").properties("name", "age", "city").primaryKeys("name").ifNotExist().create();
schema.vertexLabel("software").properties("name", "lang", "price").primaryKeys("name").ifNotExist().create();

schema.indexLabel("personByAge").onV("person").by("age").range().ifNotExist().create();
schema.indexLabel("personByCity").onV("person").by("city").secondary().ifNotExist().create();
schema.indexLabel("personByAgeAndCity").onV("person").by("age", "city").secondary().ifNotExist().create();
schema.indexLabel("softwareByPrice").onV("software").by("price").range().ifNotExist().create();

schema.edgeLabel("knows").sourceLabel("person").targetLabel("person").properties("date", "weight").ifNotExist().create();
schema.edgeLabel("created").sourceLabel("person").targetLabel("software").properties("date", "weight").ifNotExist().create();

schema.indexLabel("createdByDate").onE("created").by("date").secondary().ifNotExist().create();
schema.indexLabel("createdByWeight").onE("created").by("weight").range().ifNotExist().create();
schema.indexLabel("knowsByWeight").onE("knows").by("weight").range().ifNotExist().create();

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

{
  "vertices": [
    {
      "label": "person",
      "input": {
        "type": "file",
        "path": "example/file/vertex_person.csv",
        "format": "CSV",
        "header": ["name", "age", "city"],
        "charset": "UTF-8",
        "skipped_line": {
          "regex": "(^#|^//).*"
        }
      },
      "null_values": ["NULL", "null", ""]
    },
    {
      "label": "software",
      "input": {
        "type": "file",
        "path": "example/file/vertex_software.txt",
        "format": "TEXT",
        "delimiter": "|",
        "charset": "GBK"
      },
      "id": "id",
      "ignored": ["ISBN"]
    }
  ],
  "edges": [
    {
      "label": "knows",
      "source": ["source_name"],
      "target": ["target_name"],
      "input": {
        "type": "file",
        "path": "example/file/edge_knows.json",
        "format": "JSON",
        "date_format": "yyyyMMdd"
      },
      "field_mapping": {
        "source_name": "name",
        "target_name": "name"
      }
    },
    {
      "label": "created",
      "source": ["source_name"],
      "target": ["target_id"],
      "input": {
        "type": "file",
        "path": "example/file/edge_created.json",
        "format": "JSON",
        "date_format": "yyyy-MM-dd"
      },
      "field_mapping": {
        "source_name": "name"
      }
    }
  ]
}

4.4 执行命令导入

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

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

vertices/edges has been loaded this time : 8/6
--------------------------------------------------
count metrics
     input read success            : 14
     input read failure            : 0
     vertex parse success          : 8
     vertex parse failure          : 0
     vertex insert success         : 8
     vertex insert failure         : 0
     edge parse success            : 6
     edge parse failure            : 0
     edge insert success           : 6
     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 文件夹下，文件结构如下：

tree -f hugegraph-dataset/

hugegraph-dataset
├── hugegraph-dataset/edge_created.json
├── hugegraph-dataset/edge_knows.json
├── hugegraph-dataset/schema.groovy
├── hugegraph-dataset/struct.json
├── hugegraph-dataset/vertex_person.csv
└── hugegraph-dataset/vertex_software.txt

将文件复制到容器内部

docker cp hugegraph-dataset loader:/loader/dataset
docker exec -it loader ls /loader/dataset

edge_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 参数说明

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

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

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

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

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

HugeGraphLoader worked in NORMAL MODE
vertices/edges loaded this time : 8/6
--------------------------------------------------
count metrics
    input read success            : 14                  
    input read failure            : 0                   
    vertex parse success          : 8                   
    vertex parse failure          : 0                   
    vertex insert success         : 8                   
    vertex insert failure         : 0                   
    edge parse success            : 6                   
    edge parse failure            : 0                   
    edge insert success           : 6                   
    edge insert failure           : 0                   
--------------------------------------------------
meter metrics
    total time                    : 0.199s              
    read time                     : 0.046s              
    load time                     : 0.153s              
    vertex load time              : 0.077s              
    vertex load rate(vertices/s)  : 103                 
    edge load time                : 0.112s              
    edge load rate(edges/s)       : 53   

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

> curl "http://localhost:8080/graphs/hugegraph/graph/vertices" | gunzip
{"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 "http://localhost:8080/graphs/hugegraph/graph/edges" | gunzip

4.5.2 进入 docker 容器进行导入

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

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

sh 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）

示例：

sh bin/hugegraph-spark-loader.sh --master yarn \
--deploy-mode cluster --name spark-hugegraph-loader --file ./hugegraph.json \
--username admin --token admin --host xx.xx.xx.xx --port 8093 \
--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 这类缩写不会被识别。

--graph --schema --host --port --username --token --protocol
--trust-store-file --trust-store-password --clear-all-data --clear-timeout
--incremental-mode --failure-mode --batch-insert-threads --single-insert-threads
--max-conn --max-conn-per-route --batch-size --max-parse-errors --max-insert-errors
--timeout --shutdown-timeout --retry-times --retry-interval --check-vertex
--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。

示例：

sh bin/hugegraph-flinkcdc-loader.sh --file ./mysql-cdc.json \
--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+。 所有示例使用 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.0-release 中都支持 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+

SeaTunnel 3.0+ 官方开发文档列出 JDK 8 和 JDK 11；本文统一使用 JDK 11，并设置 JAVA_HOME。从 SeaTunnel 3.0+^[4] 获取源码，按上游开发环境文档^[5]构建发行包：

git clone --branch 3.0.0-release https://github.com/apache/seatunnel.git
cd seatunnel
./mvnw clean package -pl seatunnel-dist -am -Dmaven.test.skip=true

解压 seatunnel-dist/target/ 中生成的二进制包，后续命令都在解压后的 SeaTunnel 安装目录执行。需要更新功能时，可以切换到其他版本；引擎与连接器插件应来自同一次构建，避免混用不同版本的 JAR。

本文使用 SeaTunnel 自带的 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 数据库中准备示例数据，并让配置中的账号有读取权限：

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

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

env {
  job.mode = "BATCH"
}

source {
  Jdbc {
    url = "jdbc:mysql://mysql:3306/demo?useSSL=false&serverTimezone=UTC"
    driver = "com.mysql.cj.jdbc.Driver"
    username = "seatunnel"
    password = "change_me"
    query = "SELECT name, age FROM person ORDER BY name"
  }
}

sink {
  HugeGraph {
    host = "hugegraph"
    port = 8080
    graph_name = "hugegraph"
    graph_space = "DEFAULT"
    batch_failure_fallback = false
    mappings = [
      {
        type = "VERTEX"
        label = "person"
        idStrategy = "PRIMARY_KEY"
        idFields = ["name"]
        properties = ["name", "age"]
      }
    ]
  }
}

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

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

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

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

3.2 导入边

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

CREATE TABLE knows (
  source_name VARCHAR(64) NOT NULL,
  target_name VARCHAR(64) NOT NULL,
  since INT NOT NULL
);
INSERT INTO knows VALUES ('marko', 'vadas', 2010);

env {
  job.mode = "BATCH"
}

source {
  Jdbc {
    url = "jdbc:mysql://mysql:3306/demo?useSSL=false&serverTimezone=UTC"
    driver = "com.mysql.cj.jdbc.Driver"
    username = "seatunnel"
    password = "change_me"
    query = "SELECT source_name, target_name, since FROM knows ORDER BY source_name, target_name"
  }
}

sink {
  HugeGraph {
    host = "hugegraph"
    port = 8080
    graph_name = "hugegraph"
    graph_space = "DEFAULT"
    batch_failure_fallback = false
    check_vertex = true
    mappings = [
      {
        type = "EDGE"
        label = "knows"
        sourceConfig = {
          label = "person"
          idFields = ["source_name"]
        }
        targetConfig = {
          label = "person"
          idFields = ["target_name"]
        }
        fieldMapping = {
          source_name = "name"
          target_name = "name"
        }
        properties = ["since"]
      }
    ]
  }
}

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

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

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

g.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 顶点：

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

保存为 config/kafka2graph.conf：

env {
  job.mode = "STREAMING"
  checkpoint.interval = 10000
  sink.flush.interval = 5000
}

source {
  Kafka {
    bootstrap.servers = "kafka:9092"
    topic = "user-events"
    consumer.group = "hugegraph-import"
    start_mode = "earliest"
    format = "json"
    schema = {
      fields = {
        name = "string"
        age = "int"
      }
    }
  }
}

sink {
  HugeGraph {
    host = "hugegraph"
    port = 8080
    graph_name = "hugegraph"
    graph_space = "DEFAULT"
    batch_failure_fallback = false
    mappings = [
      {
        type = "VERTEX"
        label = "person"
        idStrategy = "PRIMARY_KEY"
        idFields = ["name"]
        properties = ["name", "age"]
      }
    ]
  }
}

./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.0-release 分支
^[5] SeaTunnel 开发环境文档
^[6] SeaTunnel 本地部署

执行引擎

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

数据源连接器

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

旧版本兼容

^[14] SeaTunnel 2.3.13 HugeGraph Sink

旧版本说明

本文面向 SeaTunnel 3.0+，文中的 Source、mappings 和图迁移示例不适用于 2.3.13。2.3.13 已过时，仅提供 HugeGraph Sink，配置使用 schema_config，并且需要提前创建图模型。如必须使用 2.3.13，请参考官方 Sink 文档^[14]，不要套用本文配置

5 - Tools Quick Start

1 HugeGraph-Tools概述

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

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

2 获取 HugeGraph-Tools

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

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

2.1 下载二进制tar包

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

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

2.2 下载源码编译安装

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

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

# 1. get from github
git clone https://github.com/apache/hugegraph-toolchain.git

# 2. 下载发布版源码包
export VERSION=1.7.0
export ARCHIVE="apache-hugegraph-toolchain-incubating-${VERSION}"
wget "https://downloads.apache.org/hugegraph/${VERSION}/${ARCHIVE}-src.tar.gz"

编译生成 tar 包:

cd hugegraph-toolchain
mvn 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

Usage: 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 设置临时环境变量，在该命令行关闭之前均有效

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

#!/bin/bash

# Set environment here if needed
#export HUGEGRAPH_URL=
#export HUGEGRAPH_GRAPH=
#export HUGEGRAPH_USERNAME=
#export HUGEGRAPH_PASSWORD=
#export HUGEGRAPH_TIMEOUT=
#export HUGEGRAPH_TRUST_STORE_FILE=
#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 具体命令参数

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

Usage: hugegraph [options] [command] [command options]
  Options:
    --graph
      Name of graph
      Default: hugegraph
    --password
      Password of user
    --throw-mode
      Whether the hugegraph-tools work to throw an exception
      Default: false
    --timeout
      Connection timeout
      Default: 30
    --trust-store-file
      The path of client truststore file used when https protocol is enabled
    --trust-store-password
      The password of the client truststore file used when the https protocol 
      is enabled
    --url
      The URL of HugeGraph-Server
      Default: http://127.0.0.1:8080
    --user
      Name of user
  Commands:
    graph-create      Create graph with config
      Usage: graph-create [options]
        Options:
          --file, -f
            Creating graph config file
          --name, -n
            The name of new created graph, default is g
            Default: g

    graph-clone      Clone graph
      Usage: graph-clone [options]
        Options:
          --clone-graph-name
            The name of cloned graph, default is hugegraph
            Default: hugegraph
          --name, -n
            The name of new created graph, default is g
            Default: g

    graph-list      List all graphs
      Usage: graph-list

    graph-get      Get graph info
      Usage: graph-get

    graph-clear      Clear graph schema and data
      Usage: graph-clear [options]
        Options:
        * --confirm-message, -c
            Confirm message of graph clear is "I'm sure to delete all data". 
            (Note: include "")

    graph-drop      Drop graph
      Usage: graph-drop [options]
        Options:
        * --confirm-message, -c
            Confirm message of graph clear is "I'm sure to drop the graph". 
            (Note: include "")

    graph-mode-set      Set graph mode
      Usage: graph-mode-set [options]
        Options:
        * --graph-mode, -m
            Graph mode, include: [NONE, RESTORING, MERGING]
            Possible Values: [NONE, RESTORING, MERGING, LOADING]

    graph-mode-get      Get graph mode
      Usage: graph-mode-get

    task-list      List tasks
      Usage: task-list [options]
        Options:
          --limit
            Limit number, no limit if not provided
            Default: -1
          --status
            Status of task

    task-get      Get task info
      Usage: task-get [options]
        Options:
        * --task-id
            Task id
            Default: 0

    task-delete      Delete task
      Usage: task-delete [options]
        Options:
        * --task-id
            Task id
            Default: 0

    task-cancel      Cancel task
      Usage: task-cancel [options]
        Options:
        * --task-id
            Task id
            Default: 0

    task-clear      Clear completed tasks
      Usage: task-clear [options]
        Options:
          --force
            Force to clear all tasks, cancel all uncompleted tasks firstly, 
            and delete all completed tasks
            Default: false

    gremlin-execute      Execute Gremlin statements
      Usage: gremlin-execute [options]
        Options:
          --aliases, -a
            Gremlin aliases, valid format is: 'key1=value1,key2=value2...'
            Default: {}
          --bindings, -b
            Gremlin bindings, valid format is: 'key1=value1,key2=value2...'
            Default: {}
          --file, -f
            Gremlin Script file to be executed, UTF-8 encoded, exclusive to 
            --script 
          --language, -l
            Gremlin script language
            Default: gremlin-groovy
          --script, -s
            Gremlin script to be executed, exclusive to --file

    gremlin-schedule      Execute Gremlin statements as asynchronous job
      Usage: gremlin-schedule [options]
        Options:
          --bindings, -b
            Gremlin bindings, valid format is: 'key1=value1,key2=value2...'
            Default: {}
          --file, -f
            Gremlin Script file to be executed, UTF-8 encoded, exclusive to 
            --script 
          --language, -l
            Gremlin script language
            Default: gremlin-groovy
          --script, -s
            Gremlin script to be executed, exclusive to --file

    backup      Backup graph schema/data. If directory is on HDFS, use -D to 
            set HDFS params. For example: 
            -Dfs.default.name=hdfs://localhost:9000 
      Usage: backup [options]
        Options:
          --all-properties
            All properties to be backup flag
            Default: false
          --compress
            compress flag
            Default: true
          --directory, -d
            Directory of graph schema/data, default is './{graphname}' in 
            local file system or '{fs.default.name}/{graphname}' in HDFS
          --format
            File format, valid is [json, text]
            Default: json
          --huge-types, -t
            Type of schema/data. Concat with ',' if more than one. Other types 
            include 'all' and 'schema'. 'all' means all vertices, edges and 
            schema. In other words, 'all' equals with 'vertex, edge, 
            vertex_label, edge_label, property_key, index_label'. 'schema' 
            equals with 'vertex_label, edge_label, property_key, index_label'.
            Default: [PROPERTY_KEY, VERTEX_LABEL, EDGE_LABEL, INDEX_LABEL, VERTEX, EDGE]
          --label
            Vertex label or edge label, only valid when type is vertex or edge
          --log, -l
            Directory of log
            Default: ./logs
          --properties
            Vertex or edge properties to backup, only valid when type is 
            vertex or edge
            Default: []
          --retry
            Retry times, default is 3
            Default: 3
          --split-size, -s
            Split size of shard
            Default: 1048576
          --thread-num, -T
            Threads number to use, default is Math.min(10, Math.max(4, CPUs / 
            2)) 
            Default: 0
          -D
            HDFS config parameters
            Syntax: -Dkey=value
            Default: {}

    schedule-backup      Schedule backup task
      Usage: schedule-backup [options]
        Options:
          --backup-num
            The number of latest backups to keep
            Default: 3
        * --directory, -d
            The directory of backups stored
          --interval
            The interval of backup, format is: "a b c d e". 'a' means minute 
            (0 - 59), 'b' means hour (0 - 23), 'c' means day of month (1 - 
            31), 'd' means month (1 - 12), 'e' means day of week (0 - 6) 
            (Sunday=0), "*" means all
            Default: "0 0 * * *"

    dump      Dump graph to files
      Usage: dump [options]
        Options:
          --directory, -d
            Directory of graph schema/data, default is './{graphname}' in 
            local file system or '{fs.default.name}/{graphname}' in HDFS
          --formatter, -f
            Formatter to customize format of vertex/edge
            Default: JsonFormatter
          --log, -l
            Directory of log
            Default: ./logs
          --retry
            Retry times, default is 3
            Default: 3
          --split-size, -s
            Split size of shard
            Default: 1048576
          --thread-num, -T
            Threads number to use, default is Math.min(10, Math.max(4, CPUs / 
            2)) 
            Default: 0
          -D
            HDFS config parameters
            Syntax: -Dkey=value
            Default: {}

    restore      Restore graph schema/data. If directory is on HDFS, use -D to 
            set HDFS params if needed. For 
            example:-Dfs.default.name=hdfs://localhost:9000 
      Usage: restore [options]
        Options:
          --clean
            Whether to remove the directory of graph data after restored
            Default: false
          --directory, -d
            Directory of graph schema/data, default is './{graphname}' in 
            local file system or '{fs.default.name}/{graphname}' in HDFS
          --huge-types, -t
            Type of schema/data. Concat with ',' if more than one. Other types 
            include 'all' and 'schema'. 'all' means all vertices, edges and 
            schema. In other words, 'all' equals with 'vertex, edge, 
            vertex_label, edge_label, property_key, index_label'. 'schema' 
            equals with 'vertex_label, edge_label, property_key, index_label'.
            Default: [PROPERTY_KEY, VERTEX_LABEL, EDGE_LABEL, INDEX_LABEL, VERTEX, EDGE]
          --log, -l
            Directory of log
            Default: ./logs
          --retry
            Retry times, default is 3
            Default: 3
          --thread-num, -T
            Threads number to use, default is Math.min(10, Math.max(4, CPUs / 
            2)) 
            Default: 0
          -D
            HDFS config parameters
            Syntax: -Dkey=value
            Default: {}

    migrate      Migrate graph
      Usage: migrate [options]
        Options:
          --directory, -d
            Directory of graph schema/data, default is './{graphname}' in 
            local file system or '{fs.default.name}/{graphname}' in HDFS
          --graph-mode, -m
            Mode used when migrating to target graph, include: [RESTORING, 
            MERGING] 
            Default: RESTORING
            Possible Values: [NONE, RESTORING, MERGING, LOADING]
          --huge-types, -t
            Type of schema/data. Concat with ',' if more than one. Other types 
            include 'all' and 'schema'. 'all' means all vertices, edges and 
            schema. In other words, 'all' equals with 'vertex, edge, 
            vertex_label, edge_label, property_key, index_label'. 'schema' 
            equals with 'vertex_label, edge_label, property_key, index_label'.
            Default: [PROPERTY_KEY, VERTEX_LABEL, EDGE_LABEL, INDEX_LABEL, VERTEX, EDGE]
          --keep-local-data
            Whether to keep the local directory of graph data after restored
            Default: false
          --log, -l
            Directory of log
            Default: ./logs
          --retry
            Retry times, default is 3
            Default: 3
          --split-size, -s
            Split size of shard
            Default: 1048576
          --target-graph
            The name of target graph to migrate
            Default: hugegraph
          --target-password
            The password of target graph to migrate
          --target-timeout
            The timeout to connect target graph to migrate
            Default: 0
          --target-trust-store-file
            The trust store file of target graph to migrate
          --target-trust-store-password
            The trust store password of target graph to migrate
          --target-url
            The url of target graph to migrate
            Default: http://127.0.0.1:8081
          --target-user
            The username of target graph to migrate
          --thread-num, -T
            Threads number to use, default is Math.min(10, Math.max(4, CPUs / 
            2)) 
            Default: 0
          -D
            HDFS config parameters
            Syntax: -Dkey=value
            Default: {}

    deploy      Install HugeGraph-Server and HugeGraph-Studio
      Usage: deploy [options]
        Options:
        * -p
            Install path of HugeGraph-Server and HugeGraph-Studio
          -u
            Download url prefix path of HugeGraph-Server and HugeGraph-Studio
        * -v
            Version of HugeGraph-Server and HugeGraph-Studio

    start-all      Start HugeGraph-Server and HugeGraph-Studio
      Usage: start-all [options]
        Options:
        * -p
            Install path of HugeGraph-Server and HugeGraph-Studio
        * -v
            Version of HugeGraph-Server and HugeGraph-Studio

    clear      Clear HugeGraph-Server and HugeGraph-Studio
      Usage: clear [options]
        Options:
        * -p
            Install path of HugeGraph-Server and HugeGraph-Studio

    stop-all      Stop HugeGraph-Server and HugeGraph-Studio
      Usage: stop-all

    auth-backup      null
      Usage: auth-backup [options]
        Options:
          --directory
            Directory of auth information, default is 
            './{auth-backup-restore}' in local file system or 
            '{fs.default.name}/{auth-backup-restore}' in HDFS
          --retry
            Retry times, default is 3
            Default: 3
          --types, -t
            Type of auth data to restore and backup, concat with ',' if more 
            than one. 'all' means all auth information. In other words, 'all' 
            equals with 'user, group, target, belong, access'. In addition, 
            'belong' or 'access' can not backup or restore alone, if type 
            contains 'belong' then should contains 'user' and 'group'. If type 
            contains 'access' then should contains 'group' and 'target'.
            Default: [TARGET, GROUP, USER, ACCESS, BELONG]
          -D
            HDFS config parameters
            Syntax: -Dkey=value
            Default: {}

    auth-restore      null
      Usage: auth-restore [options]
        Options:
          --directory
            Directory of auth information, default is 
            './{auth-backup-restore}' in local file system or 
            '{fs.default.name}/{auth-backup-restore}' in HDFS
          --init-password
            Init user password, if restore type include 'user', please specify 
            the init-password of users.
            Default: <empty string>
          --retry
            Retry times, default is 3
            Default: 3
          --strategy
            The strategy needs to be chosen in the event of a conflict when 
            restoring. Valid strategies include 'stop' and 'ignore', default 
            is 'stop'. 'stop' means if there a conflict, stop restore. 
            'ignore' means if there a conflict, ignore and continue to 
            restore. 
            Default: STOP
            Possible Values: [STOP, IGNORE]
          --types, -t
            Type of auth data to restore and backup, concat with ',' if more 
            than one. 'all' means all auth information. In other words, 'all' 
            equals with 'user, group, target, belong, access'. In addition, 
            'belong' or 'access' can not backup or restore alone, if type 
            contains 'belong' then should contains 'user' and 'group'. If type 
            contains 'access' then should contains 'group' and 'target'.
            Default: [TARGET, GROUP, USER, ACCESS, BELONG]
          -D
            HDFS config parameters
            Syntax: -Dkey=value
            Default: {}

    help      Print usage
      Usage: help

3.10 具体命令示例

1. gremlin语句

# 同步执行gremlin
./bin/hugegraph --url http://127.0.0.1:8080 --graph hugegraph gremlin-execute --script 'g.V().count()'

# 异步执行gremlin
./bin/hugegraph --url http://127.0.0.1:8080 --graph hugegraph gremlin-schedule --script 'g.V().count()'

2. 查看task情况

./bin/hugegraph --url http://127.0.0.1:8080 --graph hugegraph task-list

./bin/hugegraph --url http://127.0.0.1:8080 --graph hugegraph task-list --limit 5

./bin/hugegraph --url http://127.0.0.1:8080 --graph hugegraph task-list --status success

3. 图模式查看和设置

./bin/hugegraph --url http://127.0.0.1:8080 --graph hugegraph graph-mode-set -m RESTORING

./bin/hugegraph --url http://127.0.0.1:8080 --graph hugegraph graph-mode-get

./bin/hugegraph --url http://127.0.0.1:8080 --graph hugegraph graph-list

4. 清理图

./bin/hugegraph --url http://127.0.0.1:8080 --graph hugegraph graph-clear -c "I'm sure to delete all data"

5. 图备份

./bin/hugegraph --url http://127.0.0.1:8080 --graph hugegraph backup -t all --directory ./backup-test

6. 周期性的备份

./bin/hugegraph --url http://127.0.0.1:8080 --graph hugegraph schedule-backup -d ./backup --interval "*/2 * * * *"

7. 图恢复

# 设置图模式
./bin/hugegraph --url http://127.0.0.1:8080 --graph hugegraph graph-mode-set -m RESTORING

# 恢复图
./bin/hugegraph --url http://127.0.0.1:8080 --graph hugegraph restore -t all --directory ./backup-test

# 恢复图模式
./bin/hugegraph --url http://127.0.0.1:8080 --graph hugegraph graph-mode-set -m NONE

8. 图迁移

./bin/hugegraph --url http://127.0.0.1:8080 --graph hugegraph migrate --target-url http://127.0.0.1:8090 --target-graph hugegraph

6 - 图导出/迁移

需要备份、导出或在两张图之间迁移数据时，从这里选择工具。Tools 适合单机运维和备份；SeaTunnel Source 适合把图数据接入可扩展的数据管道。

• 使用 Tools 导出和管理图
• 使用 SeaTunnel Source 导出与迁移图数据

6.1 - 使用 SeaTunnel Source 导出与迁移图数据

如果你需要把数据从一张 HugeGraph 图复制到另一张图，使用 graph2graph：HugeGraph Source 从源图（A 图）读取顶点和边，数据经过可选的 Transform 后，由 HugeGraph Sink 写入目标图（B 图）。数据方向是 A 图 → HugeGraph Source →（可选 Transform）→ HugeGraph Sink → B 图。如果要把图数据导出到文件、JDBC、Kafka 等其他系统，则使用 graph2any，由下游 Sink 接收 Source 读取的数据。本文介绍这两类任务。

版本要求：本文面向 SeaTunnel 3.0+

开始前请先完成导入页中的通用环境准备和配置，其中包含 JDK、HOCON、插件安装和图模型说明。

1 迁移 HugeGraph 图（graph2graph）

下面从源图迁移 person 顶点和 knows 边。请使用独立的目标图：本节采用 CUSTOMIZE_STRING 保留顶点 ID，不要复用前面已经创建为 PRIMARY_KEY 的 person 标签。

这两个任务只迁移指定标签和属性，不会完整复制源图的索引、TTL 等全部 Schema 配置。运行期间应暂停源图写入，避免两个任务读到不同时间的数据；完成后核对顶点、边数量及抽样属性。

1.1 先迁移顶点

Source 自动补充 ~id 保留列，Sink 把原 ID 作为字符串保存。无需在 schema.fields 中声明 ~id，手动声明保留列会被拒绝。

env {
  job.mode = "BATCH"
}

source {
  HugeGraph {
    host = "source-hugegraph"
    port = 8080
    graph_name = "hugegraph"
    graph_space = "DEFAULT"
    label = "person"
    label_type = "VERTEX"
    schema = {
      fields = {
        name = "string"
        age = "int"
      }
    }
  }
}

sink {
  HugeGraph {
    host = "target-hugegraph"
    port = 8080
    graph_name = "hugegraph"
    graph_space = "DEFAULT"
    batch_failure_fallback = false
    mappings = [
      {
        type = "VERTEX"
        label = "person"
        idStrategy = "CUSTOMIZE_STRING"
        idFields = ["~id"]
        properties = ["name", "age"]
      }
    ]
  }
}

./bin/seatunnel.sh --config ./config/graph2graph-person.conf -m local

1.2 再迁移边

确认顶点任务成功后，使用 Source 自动补充的 ~source_id 和 ~target_id 定位端点。因为上一任务保留了原 ID，这两列可以直接引用目标图中的顶点。

env {
  job.mode = "BATCH"
}

source {
  HugeGraph {
    host = "source-hugegraph"
    port = 8080
    graph_name = "hugegraph"
    graph_space = "DEFAULT"
    label = "knows"
    label_type = "EDGE"
    schema = {
      fields = {
        since = "int"
      }
    }
  }
}

sink {
  HugeGraph {
    host = "target-hugegraph"
    port = 8080
    graph_name = "hugegraph"
    graph_space = "DEFAULT"
    check_vertex = true
    batch_failure_fallback = false
    mappings = [
      {
        type = "EDGE"
        label = "knows"
        sourceConfig = {
          label = "person"
          idFields = ["~source_id"]
        }
        targetConfig = {
          label = "person"
          idFields = ["~target_id"]
        }
        properties = ["since"]
      }
    ]
  }
}

./bin/seatunnel.sh --config ./config/graph2graph-knows.conf -m local

本例打开端点检查，并让写入错误直接导致任务失败。默认的 check_vertex = false 不保证最终一致：缺少端点可能产生悬空边，因此不能用任务成功代替迁移结果检查。

为什么保留 ID？ HugeGraph 的 PRIMARY_KEY ID 包含顶点标签的内部 ID，两张图可能不同。例如源图顶点是 1:marko，目标图重新按主键生成的可能是 2:marko。如果重新生成顶点 ID 后仍复用源图的边端点，边就会连错。本例将原 ID 保存为字符串，因此会改变目标图的 ID 策略

若要一次读取全部标签，省略 Source 的 label 后会读取 label_type（默认 VERTEX）下的全部 label，每个 label 输出一张表。这时需用 sourceTable 将各 Sink 映射绑定到对应表，例如 sourceTable = "default.person"；具体值以 Writer 日志中的完整表名为准。不能直接套用本节的单标签配置。其他限制见 HugeGraph Source 文档。

2 导出到其他系统（graph2any）

graph2any 使用 HugeGraph Source^[1] 读取顶点或边，再交给下游 Sink。下面示例将 person 顶点导出为本地 JSON 文件；导出到 JDBC、Kafka 等系统时，替换 LocalFile^[2] 及其配置即可。

env {
  job.mode = "BATCH"
}

source {
  HugeGraph {
    host = "hugegraph"
    port = 8080
    graph_name = "hugegraph"
    graph_space = "DEFAULT"
    label = "person"
    label_type = "VERTEX"
    schema = {
      fields = {
        name = "string"
        age = "int"
      }
    }
  }
}

sink {
  LocalFile {
    path = "/tmp/hugegraph-export/${table_name}"
    file_format_type = "json"
  }
}

保存为 config/graph2file-person.conf，在 SeaTunnel 安装目录执行：

./bin/seatunnel.sh --config ./config/graph2file-person.conf -m local

导出边时，将 Source 的 label 改为边标签、label_type 改为 EDGE，并在 schema.fields 中声明边属性。Source 会额外输出 ~source_id、~source_label、~target_id 和 ~target_label，这些保留列可直接写入文件或交给下游转换步骤。

本页只介绍数据行的读取和写出，不会自动复制源图的索引、TTL 或其他 Schema 设置。完整 Source 参数和通用环境说明请回到SeaTunnel 图导入文档^[3]。

3 参考文档

连接器

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

关联文档

^[3] SeaTunnel 图导入文档

7 - HugeGraph-Spark-Connector Quick Start

1 HugeGraph-Spark-Connector 概述

HugeGraph-Spark-Connector 使用 Spark DataFrame API 将批量数据写入 HugeGraph。当前实现提供顶点和边的写入器。

目前尚未实现从 HugeGraph 读取数据：表只实现了 SupportsWrite，因此不支持 spark.read.format(...)。连接器支持 CUSTOMIZE 和 PRIMARY_KEY 两种顶点 id 策略，AUTOMATIC 策略会被拒绝。

2 环境要求

• Java 8+
• Maven 3.6+
• Spark 3.2.x（模块基于 Spark 3.2.2 编译，依赖范围为 provided，因此需要由 Spark 运行环境提供 Spark 的 jar）
• Scala 2.12（基于 Scala 2.12.11 编译）

3 编译

3.1 不执行测试的编译

以下命令均在仓库根目录执行。

git clone https://github.com/apache/hugegraph-toolchain.git
cd hugegraph-toolchain
mvn clean package -pl hugegraph-spark-connector -am -DskipTests -ntp

3.2 执行默认测试的编译

mvn clean package -pl hugegraph-spark-connector -am -ntp

两条命令都会在 hugegraph-spark-connector/target/hugegraph-spark-connector-${revision}-jar-with-dependencies.jar 生成一个包含依赖的 jar（不包含 Spark 本身）。如果不通过 Maven 管理依赖，可以把它传给 spark-submit --jars。

4 使用方法

先在 pom.xml 中添加依赖，并将 ${revision} 换成实际使用的发布版本：

<dependency>
    <groupId>org.apache.hugegraph</groupId>
    <artifactId>hugegraph-spark-connector</artifactId>
    <version>${revision}</version>
</dependency>

format 必须写完整类名 org.apache.hugegraph.spark.connector.DataSource，连接器没有通过 Spark 的 DataSourceRegister 服务注册短名称。当 HugeGraphServer 开启鉴权时，需要在下面的示例中加上 .option("username", ...) 和 .option("token", ...)。

4.1 Schema 定义示例

假设我们有一个图，其 schema 定义如下：

schema.propertyKey("name").asText().ifNotExist().create()
schema.propertyKey("age").asInt().ifNotExist().create()
schema.propertyKey("city").asText().ifNotExist().create()
schema.propertyKey("weight").asDouble().ifNotExist().create()
schema.propertyKey("lang").asText().ifNotExist().create()
schema.propertyKey("date").asText().ifNotExist().create()
schema.propertyKey("price").asDouble().ifNotExist().create()

schema.vertexLabel("person")
        .properties("name", "age", "city")
        .useCustomizeStringId()
        .nullableKeys("age", "city")
        .ifNotExist()
        .create()

schema.vertexLabel("software")
        .properties("name", "lang", "price")
        .primaryKeys("name")
        .ifNotExist()
        .create()

schema.edgeLabel("knows")
        .sourceLabel("person")
        .targetLabel("person")
        .properties("date", "weight")
        .ifNotExist()
        .create()

schema.edgeLabel("created")
        .sourceLabel("person")
        .targetLabel("software")
        .properties("date", "weight")
        .ifNotExist()
        .create()