Skip to content

Commit d49bf32

Browse files
author
MStarRobotics
committed
docs: add Algorithm Job REST API documentation
Add Algorithm API documentation to the RESTful API guide. - Document algorithm job submission endpoint - Explain async task monitoring via Task API - Show how to retrieve and access algorithm results - List all supported algorithms (pagerank, lpa, wcc, etc.) - Include performance guidance for large graphs - Provide parallel English and Chinese documentation - Update navigation (SUMMARY.md) for both languages Resolves #205
1 parent ecc5622 commit d49bf32

4 files changed

Lines changed: 200 additions & 0 deletions

File tree

‎content/cn/docs/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
* [Rank](clients/restful-api/rank)
3232
* [Variable](clients/restful-api/variable)
3333
* [Graphs](clients/restful-api/graphs)
34+
* [算法](clients/restful-api/algorithm)
3435
* [Task](clients/restful-api/task)
3536
* [Gremlin](clients/restful-api/gremlin)
3637
* [Cypher](clients/restful-api/cypher)

‎content/cn/docs/clients/restful-api/algorithm.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
title: "算法 API"
3+
linkTitle: "算法"
4+
weight: 11
5+
description: "算法任务 REST API：提交和监控异步图算法任务。"
6+
---
7+
8+
### 6.1 算法
9+
10+
算法 API 允许提交长时间运行的图算法作为异步任务并跟踪其进度。
11+
12+
#### 6.1.1 提交算法任务
13+
14+
##### 方法与 URL
15+
16+
```
17+
POST http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/jobs/algorithm/{algorithm_name}
18+
```
19+
20+
对于旧版没有图空间的设置：
21+
```
22+
POST http://localhost:8080/graphs/{graph}/jobs/algorithm/{algorithm_name}
23+
```
24+
25+
##### 请求体
26+
27+
请求体因算法而异。常见参数包括：
28+
29+
- `max_iteration`: 最大迭代次数（用于 LPA 等迭代算法）
30+
- `alpha`: PageRank 的阻尼因子（默认值：0.85）
31+
- `sample_rate`: 采样率，用于 betweenness_centrality 等算法（0-1）
32+
- `direction`: 边遍历方向（OUT、IN 或 BOTH）
33+
34+
##### 示例：提交 PageRank 任务
35+
36+
```json
37+
{
38+
"alpha": 0.85,
39+
"max_iteration": 20
40+
}
41+
```
42+
43+
##### 响应状态
44+
45+
```json
46+
201
47+
```
48+
49+
##### 响应体
50+
51+
```json
52+
{
53+
"task_id": 1
54+
}
55+
```
56+
57+
响应仅包含任务 ID。使用 [任务 API](/docs/clients/restful-api/task) 监控任务。
58+
59+
#### 6.1.2 监控算法任务
60+
61+
使用 [任务 API](/docs/clients/restful-api/task) 检查算法任务的状态：
62+
63+
```
64+
GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/tasks/{task_id}
65+
```
66+
67+
#### 6.1.3 检索算法结果
68+
69+
任务完成后（task_status = "success"），算法结果作为顶点属性存储。查询顶点以访问结果：
70+
71+
```
72+
GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/graph/vertices?filter=properties.{property_name}
73+
```
74+
75+
按算法的常见结果属性名称：
76+
77+
| 算法 | 结果属性 |
78+
|------|----------|
79+
| pagerank | `page_rank` |
80+
| lpa | `community` |
81+
| wcc | `component` |
82+
| degree_centrality | `degree` |
83+
| closeness_centrality | `closeness` |
84+
| betweenness_centrality | `betweenness` |
85+
| triangle_count | `triangles` |
86+
87+
#### 6.1.4 支持的算法
88+
89+
- `pagerank`: 计算顶点重要性分数
90+
- `lpa`: 用于社区检测的标签传播算法
91+
- `wcc`: 弱连通分量
92+
- `degree_centrality`: 顶点连通性度量
93+
- `closeness_centrality`: 到其他顶点的平均距离
94+
- `betweenness_centrality`: 基于最短路径的顶点重要性
95+
- `triangle_count`: 计算图中的三角形
96+
97+
#### 6.1.5 性能考虑
98+
99+
对于非常大的图（数百万+个顶点/边），考虑使用 [HugeGraph-Computer](/docs/quickstart/computing/hugegraph-computer) 或 [HugeGraph-Vermeer](/docs/quickstart/computing/hugegraph-vermeer) 进行分布式计算，而不是 REST API。

‎content/en/docs/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
* [Rank](clients/restful-api/rank)
3232
* [Variable](clients/restful-api/variable)
3333
* [Graphs](clients/restful-api/graphs)
34+
* [Algorithm](clients/restful-api/algorithm)
3435
* [Task](clients/restful-api/task)
3536
* [Gremlin](clients/restful-api/gremlin)
3637
* [Cypher](clients/restful-api/cypher)

‎content/en/docs/clients/restful-api/algorithm.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
title: "Algorithm API"
3+
linkTitle: "Algorithm"
4+
weight: 11
5+
description: "Algorithm Job REST API: Submit and monitor asynchronous graph algorithm jobs."
6+
---
7+
8+
### 6.1 Algorithm
9+
10+
The Algorithm API allows you to submit long-running graph algorithms as asynchronous jobs and track their progress.
11+
12+
#### 6.1.1 Submit an Algorithm Job
13+
14+
##### Method & Url
15+
16+
```
17+
POST http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/jobs/algorithm/{algorithm_name}
18+
```
19+
20+
For legacy setups without graphspaces:
21+
```
22+
POST http://localhost:8080/graphs/{graph}/jobs/algorithm/{algorithm_name}
23+
```
24+
25+
##### Request Body
26+
27+
The request body varies by algorithm. Common parameters include:
28+
29+
- `max_iteration`: Maximum number of iterations (used by iterative algorithms like LPA)
30+
- `alpha`: Damping factor for PageRank (default: 0.85)
31+
- `sample_rate`: Sampling rate for algorithms like betweenness_centrality (0-1)
32+
- `direction`: Edge direction for traversal (OUT, IN, or BOTH)
33+
34+
##### Example: Submit a PageRank Job
35+
36+
```json
37+
{
38+
"alpha": 0.85,
39+
"max_iteration": 20
40+
}
41+
```
42+
43+
##### Response Status
44+
45+
```json
46+
201
47+
```
48+
49+
##### Response Body
50+
51+
```json
52+
{
53+
"task_id": 1
54+
}
55+
```
56+
57+
The response contains only the task ID. Use the [Task API](/docs/clients/restful-api/task) to monitor the job.
58+
59+
#### 6.1.2 Monitor Algorithm Job
60+
61+
Use the [Task API](/docs/clients/restful-api/task) to check the status of an algorithm job:
62+
63+
```
64+
GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/tasks/{task_id}
65+
```
66+
67+
#### 6.1.3 Retrieve Algorithm Results
68+
69+
Once the job completes (task_status = "success"), algorithm results are stored as vertex properties. Query vertices to access the results:
70+
71+
```
72+
GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/graph/vertices?filter=properties.{property_name}
73+
```
74+
75+
Common result property names by algorithm:
76+
77+
| Algorithm | Result Property |
78+
|-----------|-----------------|
79+
| pagerank | `page_rank` |
80+
| lpa | `community` |
81+
| wcc | `component` |
82+
| degree_centrality | `degree` |
83+
| closeness_centrality | `closeness` |
84+
| betweenness_centrality | `betweenness` |
85+
| triangle_count | `triangles` |
86+
87+
#### 6.1.4 Supported Algorithms
88+
89+
- `pagerank`: Compute vertex importance scores
90+
- `lpa`: Label Propagation Algorithm for community detection
91+
- `wcc`: Weakly Connected Components
92+
- `degree_centrality`: Vertex connectivity measure
93+
- `closeness_centrality`: Average distance to other vertices
94+
- `betweenness_centrality`: Vertex importance based on shortest paths
95+
- `triangle_count`: Count triangles in the graph
96+
97+
#### 6.1.5 Performance Considerations
98+
99+
For very large graphs (millions+ vertices/edges), consider using [HugeGraph-Computer](/docs/quickstart/computing/hugegraph-computer) or [HugeGraph-Vermeer](/docs/quickstart/computing/hugegraph-vermeer) for distributed computation instead of the REST API.

0 commit comments

Comments
 (0)