imbajin commented on code in PR #464: URL: https://github.com/apache/hugegraph-doc/pull/464#discussion_r4000531757
########## content/cn/docs/quickstart/toolchain/hugegraph-seatunnel-connector.md: ########## @@ -0,0 +1,410 @@ +--- +title: "HugeGraph-SeaTunnel Connector Quick Start" +linkTitle: "使用 SeaTunnel Connector 同步数据" +weight: 5 +--- + +SeaTunnel 负责连接数据源和数据目的地。HugeGraph Connector 提供两种能力。 + +- `HugeGraph Sink` 把文件、数据库、Kafka 等数据写入 HugeGraph。 +- `HugeGraph Source` 从 HugeGraph 读出顶点和边，已合入 `dev`（将随 SeaTunnel 3.0.0 发布），尚未随正式版本发布。 + + + +## 1 先看版本 + +本文把发布版和开发版分开写。配置放错版本，任务会在启动阶段失败。 + +| 使用内容 | SeaTunnel 版本 | 配置方式 | 状态 | +| --- | --- | --- | --- | +| JDBC / Kafka 写入 HugeGraph | 2.3.13 | `schema_config` | 发布版 | +| HugeGraph 读取和图迁移 | 当前 `dev` | HugeGraph Source + `mappings` | 已合入 dev，随 3.0.0 发布 | +| `graph2graph` | 当前 `dev` | Source + Sink | 已合入 dev，随 3.0.0 发布 | + +HugeGraph Source 与 `mappings` 多映射重构已随 PR [apache/seatunnel#11413](https://github.com/apache/seatunnel/pull/11413) 合入 dev（2026-08），将随 SeaTunnel **3.0.0** 正式发布。2.3.13 发行包内置 HugeGraph Client 1.5.0，dev 已升级到 1.7.0，需与 Server 版本匹配。 + +当前 `dev` 示例按 commit [`f1a1a0a`](https://github.com/apache/seatunnel/commit/f1a1a0abbe24bdac8cf23307995a78f778a3f467) 核对，固定版本的 [HugeGraph Source 文档](https://github.com/apache/seatunnel/blob/f1a1a0abbe24bdac8cf23307995a78f778a3f467/docs/zh/connectors/source/HugeGraph.md) 和 [HugeGraph Sink 文档](https://github.com/apache/seatunnel/blob/f1a1a0abbe24bdac8cf23307995a78f778a3f467/docs/zh/connectors/sink/HugeGraph.md) 与本文对应。`dev` 会继续变化，使用新版本前请重新核对配置。 + +2.3.13 的 HugeGraph Sink 使用 `schema_config`，这个版本没有 HugeGraph Source。本文所有发布版示例都按这个边界编写。 + +## 2 选哪个工具 + +先看数据从哪里来，以及任务是否已经属于一条大数据管道。 + +| 你的任务 | 推荐工具 | 适合原因 | +| --- | --- | --- | +| 管理图、执行 Gremlin、备份恢复、图克隆 | [HugeGraph-Tools](/cn/docs/quickstart/toolchain/hugegraph-tools) | 只操作 HugeGraph，命令直接 | +| 把本地文件、HDFS、MySQL 等数据批量导入 HugeGraph | [HugeGraph-Loader](/cn/docs/quickstart/toolchain/hugegraph-loader) | 配置简单，导入流程短 | +| 数据要经过 Kafka、JDBC、Flink、Spark 或多个外部系统 | SeaTunnel | 可以复用已有数据管道 | +| 需要流式任务、checkpoint 或统一管理多个连接器 | SeaTunnel | 支持 Source、Transform 和 Sink 组合 | +| 稳定地把一张 HugeGraph 图复制到另一张图 | Tools 优先 | 发布版工具更直接；SeaTunnel Source 仍是 dev 预览 | + +只维护一张图、没有现成大数据管道时，优先从 Loader 或 Tools 开始。SeaTunnel 需要额外准备连接器插件，并使用 HOCON 配置文件。 + +## 3 准备工作 + +### 3.1 HugeGraph + +本文示例使用以下图模型。 + +| 图元素 | 配置 | +| --- | --- | +| VertexLabel | `person`，主键为 `name` | +| PropertyKey | `name` 为 Text，`age` 为 Int | +| EdgeLabel | `knows`，源和目标都是 `person`，属性为 `since` | + +2.3.13 的 Sink 会按 `schema_config` 读取已有的 VertexLabel、EdgeLabel 和 PropertyKey。运行写入任务前，请先在 Hubble、REST API 或 Gremlin 中创建 Schema。 + +### 3.2 SeaTunnel + +请按 [SeaTunnel 本地部署文档](https://seatunnel.apache.org/docs/getting-started/locally/deployment/) 获取发行包。2.2.0-beta 之后，发行包默认不带连接器依赖，需要按任务安装 JDBC、Kafka 和 HugeGraph 插件；JDBC 还需要对应数据库的驱动。 + +如果 SeaTunnel 与 HugeGraph 不在同一台机器，`host` 要填写 SeaTunnel 运行环境可以访问的地址。容器内的 `127.0.0.1` 指向 SeaTunnel 容器自身；同一 Docker 网络中的服务则使用 HugeGraph 的服务名。 + +## 4 sql2graph + +JDBC 方式适合把关系库中的表或 SQL 查询结果导入 HugeGraph。下面的例子把 `person` 表写成顶点，使用 `name` 生成 HugeGraph 主键。 + + + +### 4.1 关系库到顶点 + +假设 MySQL 中有一张表。 + +```sql +CREATE TABLE person ( + name VARCHAR(64) PRIMARY KEY, + age INT NOT NULL +); +``` + +在 SeaTunnel 安装目录下创建 `config/sql2graph-person.conf`。 + +```hocon +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" + schema_config = { + type = "VERTEX" + label = "person" + idStrategy = "PRIMARY_KEY" + idFields = ["name"] + properties = ["name", "age"] + } + } +} +``` + +执行任务。 + +```bash +./bin/seatunnel.sh --config ./config/sql2graph-person.conf -m local +``` + +执行后可以在 HugeGraph 中检查顶点。 + +```groovy +g.V().hasLabel('person').valueMap('name', 'age') +``` + +`Jdbc` 的 `url` 和 `driver` 必填。`username` 和 `password` 按数据库认证配置填写，匿名连接时可以省略；示例中的密码需要替换。MySQL 驱动需要放到 SeaTunnel 对应引擎的插件目录，具体位置见 [JDBC Source 文档](https://seatunnel.apache.org/docs/connectors/source/Jdbc/)。 + +### 4.2 关系库到边 + +如果关系表中的端点字段已经能直接对应 `person.name`，可以再运行一个边任务。假设表结构如下。 + +```sql +CREATE TABLE knows ( + source_name VARCHAR(64) NOT NULL, + target_name VARCHAR(64) NOT NULL, + since INT NOT NULL +); +``` + +<details> +<summary>展开查看边任务配置</summary> + +```hocon +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" + schema_config = { + type = "EDGE" + label = "knows" + sourceConfig = { + label = "person" + idFields = ["source_name"] + } + targetConfig = { + label = "person" + idFields = ["target_name"] + } + properties = ["since"] + mapping = { + fieldMapping = { + source_name = "name" Review Comment: Confirmed the 2.3.13 validation problem against its actual connector. The final guide now targets 3.0 dev mappings: properties=["since"], separate endpoint idFields, and fieldMapping from source_name/target_name to the vertex primary key name. The dev validator excludes endpoint columns from edge properties, so the legacy extra-name-property workaround is unnecessary. The exact document edge configuration passes the dev SchemaValidator; removing fieldMapping reproduces the primary-key mismatch. Fixed in a50a72036, included in final head 18898c6885a5e7a117160252f5ebd1cf18d51eaa. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
