Skip to content

docs: refactor docs of loader & client for new version(1.7.0) #415

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
imbajin merged 11 commits into from
Dec 1, 2025
Merged

docs: refactor docs of loader & client for new version(1.7.0) #415

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
07213c0
fixed mvn version to 1.7.0
sadwitdastreetz Sep 9, 2025
17af21d
fixed wrong formats & spellings
sadwitdastreetz Sep 9, 2025
86ab30f
fixed errors && removed useless examples
sadwitdastreetz Sep 11, 2025
d412916
edited according to review
sadwitdastreetz Oct 21, 2025
0fc05c9
fixed formats problems
sadwitdastreetz Oct 22, 2025
db852d6
update loader doc for loadSource(graph) && loadOptions
sadwitdastreetz Nov 23, 2025
cf8d674
fixed minor errors
sadwitdastreetz Nov 28, 2025
5c53fcd
(fix):error in parameter description
sadwitdastreetz Nov 28, 2025
13ef946
(fix): wrong countings && indentation
sadwitdastreetz Nov 28, 2025
acbfac9
(fix): wrong explanation for client building
sadwitdastreetz Nov 28, 2025
952f68b
checked
sadwitdastreetz Nov 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 37 additions & 3 deletions content/cn/docs/clients/hugegraph-client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,12 @@ weight: 2

HugeGraph-Client 是操作 graph 的总入口，用户必须先创建出 HugeGraph-Client 对象，与 HugeGraph-Server 建立连接（伪连接）后，才能获取到 schema、graph 以及 gremlin 的操作入口对象。

目前 HugeGraph-Client 只允许连接服务端已存在的图，无法自定义图进行创建。其创建方法如下：
目前 HugeGraph-Client 只允许连接服务端已存在的图，无法自定义图进行创建。同时，需注意 1.7.0 后，构建 HugeGraph-Client 必须指定 GraphSpace（如默认 "DEFAULT"）。其创建方法如下：

```java
// HugeGraphServer 地址："http://localhost:8080"
// 图的名称："hugegraph"
HugeClient hugeClient = HugeClient.builder("http://localhost:8080", "hugegraph")
HugeClient hugeClient = HugeClient.builder("http://localhost:8080", "DEFAULT", "hugegraph")
.configTimeout(20) // 默认 20s 超时
.configUser("**", "**") // 默认未开启用户权限
.build();
Expand Down Expand Up @@ -455,6 +455,40 @@ Edge knows1 = marko.addEdge("knows", vadas, "city", "Beijing");

**注意：当 frequency 为 multiple 时必须要设置 sortKeys 对应属性类型的值。**

### 4 简单示例
### 4 图管理
client支持一个物理部署中多个 GraphSpace，每个 GraphSpace 下可以含多个图（graph）。
- 兼容：不指定 GraphSpace 时，默认使用 "DEFAULT" 空间

#### 4.1 创建GraphSpace

```java
GraphSpaceManager spaceManager = hugeClient.graphSpace();

// 定义 GraphSpace 配置
GraphSpace graphSpace = new GraphSpace();
graphSpace.setName("myGraphSpace");
graphSpace.setDescription("Business data graph space");
graphSpace.setMaxGraphNumber(10); // 最大图数量
graphSpace.setMaxRoleNumber(100); // 最大角色数量

// 创建 GraphSpace
spaceManager.createGraphSpace(graphSpace);
```
#### 4.2 GraphSpace 接口汇总

| 类别 | 接口 | 描述 |
|------|------|------|
| Manager - 查询 | listGraphSpace() | 获取所有 GraphSpace 列表 |
| | getGraphSpace(String name) | 获取指定 GraphSpace |
| Manager - 创建/更新 | createGraphSpace(GraphSpace) | 创建 GraphSpace |
| | updateGraphSpace(String, GraphSpace) | 更新配置 |
| Manager - 删除 | removeGraphSpace(String) | 删除指定 GraphSpace |
| GraphSpace - 属性 | getName() / getDescription() | 获取名称/描述 |
| | getGraphNumber() | 获取图数量 |
| GraphSpace - 配置 | setDescription(String) | 设置描述 |
| | setMaxGraphNumber(int) | 设置最大图数量 |


### 5 简单示例

简单示例见[HugeGraph-Client](/cn/docs/quickstart/client/hugegraph-client)
15 changes: 10 additions & 5 deletions content/cn/docs/quickstart/client/hugegraph-client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ weight: 1
<groupId>org.apache.hugegraph</groupId>
<artifactId>hugegraph-client</artifactId>
<!-- Update to the latest release version -->
<version>1.5.0</version>
<version>1.7.0</version>
</dependency>
</dependencies>
```
Expand Down Expand Up @@ -79,7 +79,10 @@ public class SingleExample {
public static void main(String[] args) throws IOException {
// If connect failed will throw a exception.
HugeClient hugeClient = HugeClient.builder("http://localhost:8080",
"DEFAULT",
"hugegraph")
.configUser("username", "password")
// 这是示例,生产环境需要使用安全的凭证
.build();

SchemaManager schema = hugeClient.schema();
Expand Down Expand Up @@ -224,8 +227,11 @@ public class BatchExample {
public static void main(String[] args) {
// If connect failed will throw a exception.
HugeClient hugeClient = HugeClient.builder("http://localhost:8080",
"DEFAULT",
"hugegraph")
.build();
.configUser("username", "password")
// 这是示例,生产环境需要使用安全的凭证
.build();

Copy link
Member

@imbajin imbajin Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ 代码风格问题：缩进不一致

这里的缩进与上下文不一致，建议使用相同的缩进风格：

```suggestion
.configUser("username", "password")
// 这是示例，生产环境需要使用安全的凭证
.build();
```

应保持一致的缩进，使用空格对齐。

SchemaManager schema = hugeClient.schema();

Expand Down Expand Up @@ -348,12 +354,11 @@ public class BatchExample {
}
```

### 4.4 运行 Example
#### 4.4 运行 Example

运行 Example 之前需要启动 Server,
启动过程见[HugeGraph-Server Quick Start](/cn/docs/quickstart/hugegraph-server)

### 4.5 详细 API 说明
#### 4.5 详细 API 说明

示例说明见[HugeGraph-Client 基本 API 介绍](/cn/docs/clients/hugegraph-client)

39 changes: 32 additions & 7 deletions content/cn/docs/quickstart/toolchain/hugegraph-loader.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -601,7 +601,7 @@ bin/mapping-convert.sh struct.json

##### 3.3.2 输入源

输入源目前分为四类：FILE、HDFS、JDBC、KAFKA，由`type`节点区分，我们称为本地文件输入源、HDFS 输入源、JDBC 输入源和 KAFKA 输入源，下面分别介绍。
输入源目前分为五类：FILE、HDFS、JDBC、KAFKA、GRAPH，由`type`节点区分，我们称为本地文件输入源、HDFS 输入源、JDBC 输入源和 KAFKA 输入源，图数据源，下面分别介绍。

###### 3.3.2.1 本地文件输入源

Expand Down Expand Up @@ -705,6 +705,22 @@ schema: 必填
- skipped_line：想跳过的行，复合结构，目前只能配置要跳过的行的正则表达式，用子节点 regex 描述，默认不跳过任何行，选填；
- early_stop：某次从 Kafka broker 拉取的记录为空，停止任务，默认为 false，仅用于调试，选填；

###### 3.3.2.5 GRAPH 输入源

- type：输入源类型，必须填 `graph` 或 `GRAPH`，必填；
- graphspace：源图空间名称，默认为 `DEFAULT`；
- graph： 源图名称，必填；
- username：HugeGraph 用户名；
- password：HugeGraph 密码；
- selected_vertices：要同步的顶点筛选规则；
- ignored_vertices：要忽略的顶点筛选规则；
- selected_edges：要同步的边筛选规则；
- ignored_edges：要忽略的边筛选规则；
- pd-peers：HugeGraph-PD 节点地址；
- meta-endpoints：源集群 Meta服务端点；
- cluster：源集群名称；
- batch_size：批量读取源图数据的批次大小，默认为500；

##### 3.3.3 顶点和边映射

顶点和边映射的节点（JSON 文件中的一个 key）有很多相同的部分，下面先介绍相同部分，再分别介绍`顶点映射`和`边映射`的特有节点。
Expand Down Expand Up @@ -790,20 +806,29 @@ schema: 必填
| 参数 | 默认值 | 是否必传 | 描述信息 |
|---------------------------|-----------|------|-------------------------------------------------------------------|
| `-f` 或 `--file` | | Y | 配置脚本的路径 |
| `-g` 或 `--graph` | | Y | 图数据库空间 |
| `-s` 或 `--schema` | | Y | schema 文件路径 | |
| `-h` 或 `--host` | localhost | | HugeGraphServer 的地址 |
| `-g` 或 `--graph` | | Y | 图名称 |
| `-gs` 或 `--graphspace` | DEFAULT | | 图空间 |
| `-s` 或 `--schema` | | Y | schema 文件路径 |
| `-h` 或 `--host` 或 `-i` | localhost | | HugeGraphServer 的地址 |
| `-p` 或 `--port` | 8080 | | HugeGraphServer 的端口号 |
| `--username` | null | | 当 HugeGraphServer 开启了权限认证时，当前图的 username |
| `--password` | null | | 当 HugeGraphServer 开启了权限认证时，当前图的 password |
| `--create-graph` | false | | 是否在图不存在时自动创建 |
| `--token` | null | | 当 HugeGraphServer 开启了权限认证时，当前图的 token |
| `--protocol` | http | | 向服务端发请求的协议，可选 http 或 https |
| `--pd-peers` | | | PD 服务节点地址 |
| `--pd-token` | | | 访问 PD 服务的 token |
| `--meta-endpoints` | | | 元信息存储服务地址 |
| `--direct` | false | | 是否直连 HugeGraph-Store |
| `--route-type` | NODE_PORT | | 路由选择方式（可选值：NODE_PORT / DDS / BOTH） |
| `--cluster` | hg | | 集群名 |
| `--trust-store-file` | | | 请求协议为 https 时，客户端的证书文件路径 |
| `--trust-store-password` | | | 请求协议为 https 时，客户端证书密码 |
| `--clear-all-data` | false | | 导入数据前是否清除服务端的原有数据 |
| `--clear-timeout` | 240 | | 导入数据前清除服务端的原有数据的超时时间 |
| `--incremental-mode` | false | | 是否使用断点续导模式，仅输入源为 FILE 和 HDFS 支持该模式，启用该模式能从上一次导入停止的地方开始导 |
| `--incremental-mode` | false | | 是否使用断点续导模式，仅输入源为 FILE 和 HDFS 支持该模式，启用该模式能从上一次导入停止的地方开始导入 |
| `--failure-mode` | false | | 失败模式为 true 时，会导入之前失败了的数据，一般来说失败数据文件需要在人工更正编辑好后，再次进行导入 |
| `--batch-insert-threads` | CPUs | | 批量插入线程池大小 (CPUs 是当前 OS 可用可用**逻辑核**个数) |
| `--batch-insert-threads` | CPUs | | 批量插入线程池大小 (CPUs 是当前 OS 可用**逻辑核**个数) |
| `--single-insert-threads` | 8 | | 单条插入线程池的大小 |
| `--max-conn` | 4 * CPUs | | HugeClient 与 HugeGraphServer 的最大 HTTP 连接数，**调整线程**的时候建议同时调整此项 |
| `--max-conn-per-route` | 2 * CPUs | | HugeClient 与 HugeGraphServer 每个路由的最大 HTTP 连接数，**调整线程**的时候建议同时调整此项 |
Expand All @@ -817,7 +842,7 @@ schema: 必填
| `--check-vertex` | false | | 插入边时是否检查边所连接的顶点是否存在 |
Copy link
Member

@imbajin imbajin Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 格式问题：表格末尾多余空格

这行末尾有多余的空格列分隔符，建议移除：

```suggestion
| `--help` | false | | 打印帮助信息 |
```

| `--print-progress` | true | | 是否在控制台实时打印导入条数 |
| `--dry-run` | false | | 打开该模式，只解析不导入，通常用于测试 |
| `--help` | false | | 打印帮助信息 |
| `--help` | false | | 打印帮助信息 | |

##### 3.4.2 断点续导模式

Expand Down
38 changes: 36 additions & 2 deletions content/en/docs/clients/hugegraph-client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ The `gremlin(groovy)` written by the user in `HugeGraph-Studio` can refer to the

HugeGraph-Client is the general entry for operating graph. Users must first create a HugeGraph-Client object and establish a connection (pseudo connection) with HugeGraph-Server before they can obtain the operation entry objects of schema, graph and gremlin.

Currently, HugeGraph-Client only allows connections to existing graphs on the server, and cannot create custom graphs. Its creation method is as follows:
Currently, HugeGraph-Client only allows connections to existing graphs on the server, and cannot create custom graphs. Meanwhile, it should be noted that starting from version 1.7.0, building the HugeGraph-Client must specify a GraphSpace (e.g., the default "DEFAULT"). Its creation method is as follows:

```java
// HugeGraphServer address: "http://localhost:8080"
Expand Down Expand Up @@ -444,6 +444,40 @@ Edge knows1 = marko.addEdge("knows", vadas, "city", "Beijing");

**Note: When frequency is multiple, the value of the property type corresponding to sortKeys must be set.**

### 4 Examples
### 4 GraphSpace
The client supports multiple GraphSpaces in one physical deployment, and each GraphSpace can contain multiple graphs.
- Compatibility: When no GraphSpace is specified, the "DEFAULT" space is used by default.

#### 4.1 Create GraphSpace

```java
GraphSpaceManager spaceManager = hugeClient.graphSpace();

// Define GraphSpace configuration
GraphSpace graphSpace = new GraphSpace();
graphSpace.setName("myGraphSpace");
graphSpace.setDescription("Business data graph space");
graphSpace.setMaxGraphNumber(10); // Maximum number of graphs
graphSpace.setMaxRoleNumber(100); // Maximum number of roles

// Create GraphSpace
spaceManager.createGraphSpace(graphSpace);
```

#### 4.2 GraphSpace Interface Summary

| Category | Interface | Description |
|----------|-----------|-------------|
| Manager - Query | listGraphSpace() | Get the list of all GraphSpaces |
| | getGraphSpace(String name) | Get the specified GraphSpace |
| Manager - Create/Update | createGraphSpace(GraphSpace) | Create a GraphSpace |
| | updateGraphSpace(String, GraphSpace) | Update configuration |
| Manager - Delete | removeGraphSpace(String) | Delete the specified GraphSpace |
| GraphSpace - Properties | getName() / getDescription() | Get name / description |
| | getGraphNumber() | Get the number of graphs |
| GraphSpace - Configuration | setDescription(String) | Set description |
| | setMaxGraphNumber(int) | Set the maximum number of graphs |

### 5 Simple Example

Simple examples can reference [HugeGraph-Client](/docs/quickstart/client/hugegraph-client)
14 changes: 9 additions & 5 deletions content/en/docs/quickstart/client/hugegraph-client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ Using IDEA or Eclipse to create the project:
<groupId>org.apache.hugegraph</groupId>
<artifactId>hugegraph-client</artifactId>
<!-- Update to the latest release version -->
<version>1.5.0</version>
<version>1.7.0</version>
</dependency>
</dependencies>
```
Expand Down Expand Up @@ -75,7 +75,10 @@ public class SingleExample {
public static void main(String[] args) throws IOException {
// If connect failed will throw a exception.
HugeClient hugeClient = HugeClient.builder("http://localhost:8080",
"DEFAULT",
"hugegraph")
.configUser("username", "password")
// This is an example. In a production environment, secure credentials should be used.
.build();

SchemaManager schema = hugeClient.schema();
Expand Down Expand Up @@ -218,9 +221,11 @@ import org.apache.hugegraph.structure.graph.Vertex;
public class BatchExample {

public static void main(String[] args) {
// If connect failed will throw a exception.
HugeClient hugeClient = HugeClient.builder("http://localhost:8080",
"DEFAULT",
"hugegraph")
.configUser("username", "password")
// This is an example. In a production environment, secure credentials should be used.
.build();

SchemaManager schema = hugeClient.schema();
Expand Down Expand Up @@ -344,11 +349,10 @@ public class BatchExample {
}
```

### 4.4 Run The Example
#### 4.4 Run The Example

Before running Example, you need to start the Server. For the startup process, see[HugeGraph-Server Quick Start](/docs/quickstart/hugegraph/hugegraph-server).

### 4.5 More Information About Client-API
#### 4.5 More Information About Client-API

See[Introduce basic API of HugeGraph-Client](/docs/clients/hugegraph-client).

Loading