From d49bf32c92ee63c8a67d0d8f011c81d946dfd525 Mon Sep 17 00:00:00 2001 From: MStarRobotics Date: Fri, 1 May 2026 01:05:58 +0530 Subject: [PATCH 1/2] 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 --- content/cn/docs/SUMMARY.md | 1 + .../cn/docs/clients/restful-api/algorithm.md | 99 +++++++++++++++++++ content/en/docs/SUMMARY.md | 1 + .../en/docs/clients/restful-api/algorithm.md | 99 +++++++++++++++++++ 4 files changed, 200 insertions(+) create mode 100644 content/cn/docs/clients/restful-api/algorithm.md create mode 100644 content/en/docs/clients/restful-api/algorithm.md diff --git a/content/cn/docs/SUMMARY.md b/content/cn/docs/SUMMARY.md index ab5e32bf9..ee69c4bb8 100644 --- a/content/cn/docs/SUMMARY.md +++ b/content/cn/docs/SUMMARY.md @@ -31,6 +31,7 @@ * [Rank](clients/restful-api/rank) * [Variable](clients/restful-api/variable) * [Graphs](clients/restful-api/graphs) + * [算法](clients/restful-api/algorithm) * [Task](clients/restful-api/task) * [Gremlin](clients/restful-api/gremlin) * [Cypher](clients/restful-api/cypher) diff --git a/content/cn/docs/clients/restful-api/algorithm.md b/content/cn/docs/clients/restful-api/algorithm.md new file mode 100644 index 000000000..da6a62941 --- /dev/null +++ b/content/cn/docs/clients/restful-api/algorithm.md @@ -0,0 +1,99 @@ +--- +title: "算法 API" +linkTitle: "算法" +weight: 11 +description: "算法任务 REST API：提交和监控异步图算法任务。" +--- + +### 6.1 算法 + +算法 API 允许提交长时间运行的图算法作为异步任务并跟踪其进度。 + +#### 6.1.1 提交算法任务 + +##### 方法与 URL + +``` +POST http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/jobs/algorithm/{algorithm_name} +``` + +对于旧版没有图空间的设置： +``` +POST http://localhost:8080/graphs/{graph}/jobs/algorithm/{algorithm_name} +``` + +##### 请求体 + +请求体因算法而异。常见参数包括： + +- `max_iteration`: 最大迭代次数（用于 LPA 等迭代算法） +- `alpha`: PageRank 的阻尼因子（默认值：0.85） +- `sample_rate`: 采样率，用于 betweenness_centrality 等算法（0-1） +- `direction`: 边遍历方向（OUT、IN 或 BOTH） + +##### 示例：提交 PageRank 任务 + +```json +{ + "alpha": 0.85, + "max_iteration": 20 +} +``` + +##### 响应状态 + +```json +201 +``` + +##### 响应体 + +```json +{ + "task_id": 1 +} +``` + +响应仅包含任务 ID。使用 [任务 API](/docs/clients/restful-api/task) 监控任务。 + +#### 6.1.2 监控算法任务 + +使用 [任务 API](/docs/clients/restful-api/task) 检查算法任务的状态： + +``` +GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/tasks/{task_id} +``` + +#### 6.1.3 检索算法结果 + +任务完成后（task_status = "success"），算法结果作为顶点属性存储。查询顶点以访问结果： + +``` +GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/graph/vertices?filter=properties.{property_name} +``` + +按算法的常见结果属性名称： + +| 算法 | 结果属性 | +|------|----------| +| pagerank | `page_rank` | +| lpa | `community` | +| wcc | `component` | +| degree_centrality | `degree` | +| closeness_centrality | `closeness` | +| betweenness_centrality | `betweenness` | +| triangle_count | `triangles` | + +#### 6.1.4 支持的算法 + +- `pagerank`: 计算顶点重要性分数 +- `lpa`: 用于社区检测的标签传播算法 +- `wcc`: 弱连通分量 +- `degree_centrality`: 顶点连通性度量 +- `closeness_centrality`: 到其他顶点的平均距离 +- `betweenness_centrality`: 基于最短路径的顶点重要性 +- `triangle_count`: 计算图中的三角形 + +#### 6.1.5 性能考虑 + +对于非常大的图（数百万+个顶点/边），考虑使用 [HugeGraph-Computer](/docs/quickstart/computing/hugegraph-computer) 或 [HugeGraph-Vermeer](/docs/quickstart/computing/hugegraph-vermeer) 进行分布式计算，而不是 REST API。 diff --git a/content/en/docs/SUMMARY.md b/content/en/docs/SUMMARY.md index 44321bcfe..07824d7fa 100644 --- a/content/en/docs/SUMMARY.md +++ b/content/en/docs/SUMMARY.md @@ -31,6 +31,7 @@ * [Rank](clients/restful-api/rank) * [Variable](clients/restful-api/variable) * [Graphs](clients/restful-api/graphs) + * [Algorithm](clients/restful-api/algorithm) * [Task](clients/restful-api/task) * [Gremlin](clients/restful-api/gremlin) * [Cypher](clients/restful-api/cypher) diff --git a/content/en/docs/clients/restful-api/algorithm.md b/content/en/docs/clients/restful-api/algorithm.md new file mode 100644 index 000000000..5d989284f --- /dev/null +++ b/content/en/docs/clients/restful-api/algorithm.md @@ -0,0 +1,99 @@ +--- +title: "Algorithm API" +linkTitle: "Algorithm" +weight: 11 +description: "Algorithm Job REST API: Submit and monitor asynchronous graph algorithm jobs." +--- + +### 6.1 Algorithm + +The Algorithm API allows you to submit long-running graph algorithms as asynchronous jobs and track their progress. + +#### 6.1.1 Submit an Algorithm Job + +##### Method & Url + +``` +POST http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/jobs/algorithm/{algorithm_name} +``` + +For legacy setups without graphspaces: +``` +POST http://localhost:8080/graphs/{graph}/jobs/algorithm/{algorithm_name} +``` + +##### Request Body + +The request body varies by algorithm. Common parameters include: + +- `max_iteration`: Maximum number of iterations (used by iterative algorithms like LPA) +- `alpha`: Damping factor for PageRank (default: 0.85) +- `sample_rate`: Sampling rate for algorithms like betweenness_centrality (0-1) +- `direction`: Edge direction for traversal (OUT, IN, or BOTH) + +##### Example: Submit a PageRank Job + +```json +{ + "alpha": 0.85, + "max_iteration": 20 +} +``` + +##### Response Status + +```json +201 +``` + +##### Response Body + +```json +{ + "task_id": 1 +} +``` + +The response contains only the task ID. Use the [Task API](/docs/clients/restful-api/task) to monitor the job. + +#### 6.1.2 Monitor Algorithm Job + +Use the [Task API](/docs/clients/restful-api/task) to check the status of an algorithm job: + +``` +GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/tasks/{task_id} +``` + +#### 6.1.3 Retrieve Algorithm Results + +Once the job completes (task_status = "success"), algorithm results are stored as vertex properties. Query vertices to access the results: + +``` +GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/graph/vertices?filter=properties.{property_name} +``` + +Common result property names by algorithm: + +| Algorithm | Result Property | +|-----------|-----------------| +| pagerank | `page_rank` | +| lpa | `community` | +| wcc | `component` | +| degree_centrality | `degree` | +| closeness_centrality | `closeness` | +| betweenness_centrality | `betweenness` | +| triangle_count | `triangles` | + +#### 6.1.4 Supported Algorithms + +- `pagerank`: Compute vertex importance scores +- `lpa`: Label Propagation Algorithm for community detection +- `wcc`: Weakly Connected Components +- `degree_centrality`: Vertex connectivity measure +- `closeness_centrality`: Average distance to other vertices +- `betweenness_centrality`: Vertex importance based on shortest paths +- `triangle_count`: Count triangles in the graph + +#### 6.1.5 Performance Considerations + +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. From e46d841587374d525398c79cd0b716935fd04f7c Mon Sep 17 00:00:00 2001 From: MStarRobotics Date: Fri, 1 May 2026 01:54:41 +0530 Subject: [PATCH 2/2] docs: add Algorithm Job API documentation and result persistence #205 --- content/cn/docs/SUMMARY.md | 2 +- .../cn/docs/clients/restful-api/algorithm.md | 90 ++++++++++-------- .../en/docs/clients/restful-api/algorithm.md | 94 +++++++++++-------- 3 files changed, 105 insertions(+), 81 deletions(-) diff --git a/content/cn/docs/SUMMARY.md b/content/cn/docs/SUMMARY.md index ee69c4bb8..9c3f27c0c 100644 --- a/content/cn/docs/SUMMARY.md +++ b/content/cn/docs/SUMMARY.md @@ -31,7 +31,7 @@ * [Rank](clients/restful-api/rank) * [Variable](clients/restful-api/variable) * [Graphs](clients/restful-api/graphs) - * [算法](clients/restful-api/algorithm) + * [Algorithm](clients/restful-api/algorithm) * [Task](clients/restful-api/task) * [Gremlin](clients/restful-api/gremlin) * [Cypher](clients/restful-api/cypher) diff --git a/content/cn/docs/clients/restful-api/algorithm.md b/content/cn/docs/clients/restful-api/algorithm.md index da6a62941..3bf17442a 100644 --- a/content/cn/docs/clients/restful-api/algorithm.md +++ b/content/cn/docs/clients/restful-api/algorithm.md @@ -1,28 +1,29 @@ --- title: "算法 API" linkTitle: "算法" -weight: 11 +weight: 12.5 description: "算法任务 REST API：提交和监控异步图算法任务。" --- -### 6.1 算法 +## 6.2 算法 算法 API 允许提交长时间运行的图算法作为异步任务并跟踪其进度。 -#### 6.1.1 提交算法任务 +### 6.2.1 提交算法任务 -##### 方法与 URL +#### 方法与 URL -``` +```bash POST http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/jobs/algorithm/{algorithm_name} ``` 对于旧版没有图空间的设置： -``` + +```bash POST http://localhost:8080/graphs/{graph}/jobs/algorithm/{algorithm_name} ``` -##### 请求体 +#### 请求体 请求体因算法而异。常见参数包括： @@ -31,7 +32,7 @@ POST http://localhost:8080/graphs/{graph}/jobs/algorithm/{algorithm_name} - `sample_rate`: 采样率，用于 betweenness_centrality 等算法（0-1） - `direction`: 边遍历方向（OUT、IN 或 BOTH） -##### 示例：提交 PageRank 任务 +#### 示例：提交 PageRank 任务 ```json { @@ -40,13 +41,13 @@ POST http://localhost:8080/graphs/{graph}/jobs/algorithm/{algorithm_name} } ``` -##### 响应状态 +#### 响应状态 ```json 201 ``` -##### 响应体 +#### 响应体 ```json { @@ -54,46 +55,57 @@ POST http://localhost:8080/graphs/{graph}/jobs/algorithm/{algorithm_name} } ``` -响应仅包含任务 ID。使用 [任务 API](/docs/clients/restful-api/task) 监控任务。 +响应仅包含任务 ID。使用 [任务 API](./task) 监控任务。 -#### 6.1.2 监控算法任务 +### 6.2.2 监控算法任务 -使用 [任务 API](/docs/clients/restful-api/task) 检查算法任务的状态： +使用 [任务 API](./task) 检查算法任务的状态： -``` +```bash GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/tasks/{task_id} ``` -#### 6.1.3 检索算法结果 +### 6.2.3 检索算法结果 -任务完成后（task_status = "success"），算法结果作为顶点属性存储。查询顶点以访问结果： +响应体是算法相关的。有些算法直接返回 JSON，有些算法还会把结果写回到顶点属性。 -``` -GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/graph/vertices?filter=properties.{property_name} -``` +示例： -按算法的常见结果属性名称： +- `page_rank` 会把排名写入 `r_rank` 顶点属性。 +- `lpa` 和 `weak_connected_component` 会把社区标签写入 `c_label` 顶点属性。 -| 算法 | 结果属性 | -|------|----------| -| pagerank | `page_rank` | -| lpa | `community` | -| wcc | `component` | -| degree_centrality | `degree` | -| closeness_centrality | `closeness` | -| betweenness_centrality | `betweenness` | -| triangle_count | `triangles` | +这些名称来自算法任务实现，可能与 HugeGraph 其他组件使用的属性名不同。 -#### 6.1.4 支持的算法 +如果某个任务会写回顶点，请使用常规的 Vertex API，并按照算法更新的属性进行查询。 -- `pagerank`: 计算顶点重要性分数 -- `lpa`: 用于社区检测的标签传播算法 -- `wcc`: 弱连通分量 -- `degree_centrality`: 顶点连通性度量 -- `closeness_centrality`: 到其他顶点的平均距离 -- `betweenness_centrality`: 基于最短路径的顶点重要性 -- `triangle_count`: 计算图中的三角形 +例如，要查找 PageRank 大于 0 的顶点，可以使用： -#### 6.1.5 性能考虑 +```bash +GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/graph/vertices?properties={"r_rank":"P.gt(0)"} +``` -对于非常大的图（数百万+个顶点/边），考虑使用 [HugeGraph-Computer](/docs/quickstart/computing/hugegraph-computer) 或 [HugeGraph-Vermeer](/docs/quickstart/computing/hugegraph-vermeer) 进行分布式计算，而不是 REST API。 +### 6.2.4 支持的算法 + +服务端在 `AlgorithmPool` 中注册了以下算法名称： + +- `count_vertex` +- `count_edge` +- `degree_centrality` +- `stress_centrality` +- `betweenness_centrality` +- `closeness_centrality` +- `eigenvector_centrality` +- `triangle_count` +- `cluster_coefficient` +- `lpa` +- `louvain` +- `weak_connected_component` +- `fusiform_similarity` +- `rings` +- `k_core` +- `page_rank` +- `subgraph_stat` + +### 6.2.5 性能考虑 + +对于非常大的图（数百万+个顶点/边），考虑使用 [HugeGraph-Computer](/cn/docs/quickstart/computing/hugegraph-computer) 或 [HugeGraph-Vermeer](/cn/docs/quickstart/computing/hugegraph-vermeer) 进行分布式计算，而不是 REST API。 diff --git a/content/en/docs/clients/restful-api/algorithm.md b/content/en/docs/clients/restful-api/algorithm.md index 5d989284f..458d5c825 100644 --- a/content/en/docs/clients/restful-api/algorithm.md +++ b/content/en/docs/clients/restful-api/algorithm.md @@ -1,28 +1,29 @@ --- title: "Algorithm API" linkTitle: "Algorithm" -weight: 11 +weight: 12.5 description: "Algorithm Job REST API: Submit and monitor asynchronous graph algorithm jobs." --- -### 6.1 Algorithm +## 6.2 Algorithm The Algorithm API allows you to submit long-running graph algorithms as asynchronous jobs and track their progress. -#### 6.1.1 Submit an Algorithm Job +### 6.2.1 Submit an Algorithm Job -##### Method & Url +#### Method & Url -``` +```bash POST http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/jobs/algorithm/{algorithm_name} ``` For legacy setups without graphspaces: -``` + +```bash POST http://localhost:8080/graphs/{graph}/jobs/algorithm/{algorithm_name} ``` -##### Request Body +#### Request Body The request body varies by algorithm. Common parameters include: @@ -31,7 +32,7 @@ The request body varies by algorithm. Common parameters include: - `sample_rate`: Sampling rate for algorithms like betweenness_centrality (0-1) - `direction`: Edge direction for traversal (OUT, IN, or BOTH) -##### Example: Submit a PageRank Job +#### Example: Submit a PageRank Job ```json { @@ -40,13 +41,13 @@ The request body varies by algorithm. Common parameters include: } ``` -##### Response Status +#### Response Status ```json 201 ``` -##### Response Body +#### Response Body ```json { @@ -54,46 +55,57 @@ The request body varies by algorithm. Common parameters include: } ``` -The response contains only the task ID. Use the [Task API](/docs/clients/restful-api/task) to monitor the job. +The response contains only the task ID. Use the [Task API](./task) to monitor the job. -#### 6.1.2 Monitor Algorithm Job +### 6.2.2 Monitor Algorithm Job -Use the [Task API](/docs/clients/restful-api/task) to check the status of an algorithm job: +Use the [Task API](./task) to check the status of an algorithm job: -``` +```bash GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/tasks/{task_id} ``` -#### 6.1.3 Retrieve Algorithm Results +### 6.2.3 Retrieve Algorithm Results -Once the job completes (task_status = "success"), algorithm results are stored as vertex properties. Query vertices to access the results: +The response body is algorithm-specific. Some algorithms return JSON directly, while others also write results back to vertex properties. -``` -GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/graph/vertices?filter=properties.{property_name} +Examples: + +- `page_rank` writes rank values to the `r_rank` vertex property. +- `lpa` and `weak_connected_component` write community labels to the `c_label` vertex property. + +These names come from the algorithm job implementation and can differ from property names used by other HugeGraph components. + +If a job writes back to vertices, query the graph with the normal vertex API and filter by the property the algorithm updates. + +For example, to find vertices with a PageRank value greater than zero, use: + +```bash +GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/graph/vertices?properties={"r_rank":"P.gt(0)"} ``` -Common result property names by algorithm: - -| Algorithm | Result Property | -|-----------|-----------------| -| pagerank | `page_rank` | -| lpa | `community` | -| wcc | `component` | -| degree_centrality | `degree` | -| closeness_centrality | `closeness` | -| betweenness_centrality | `betweenness` | -| triangle_count | `triangles` | - -#### 6.1.4 Supported Algorithms - -- `pagerank`: Compute vertex importance scores -- `lpa`: Label Propagation Algorithm for community detection -- `wcc`: Weakly Connected Components -- `degree_centrality`: Vertex connectivity measure -- `closeness_centrality`: Average distance to other vertices -- `betweenness_centrality`: Vertex importance based on shortest paths -- `triangle_count`: Count triangles in the graph - -#### 6.1.5 Performance Considerations +### 6.2.4 Supported Algorithms + +The server registers the following algorithm names in `AlgorithmPool`: + +- `count_vertex` +- `count_edge` +- `degree_centrality` +- `stress_centrality` +- `betweenness_centrality` +- `closeness_centrality` +- `eigenvector_centrality` +- `triangle_count` +- `cluster_coefficient` +- `lpa` +- `louvain` +- `weak_connected_component` +- `fusiform_similarity` +- `rings` +- `k_core` +- `page_rank` +- `subgraph_stat` + +### 6.2.5 Performance Considerations 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.