Copilot commented on code in PR #458: URL: https://github.com/apache/hugegraph-doc/pull/458#discussion_r3186187058
########## content/en/docs/clients/restful-api/algorithm.md: ########## @@ -0,0 +1,111 @@ +--- +title: "Algorithm API" +linkTitle: "Algorithm" +weight: 12.5 +description: "Algorithm Job REST API: Submit and monitor asynchronous graph algorithm jobs." +--- + +## 6.2 Algorithm + +The Algorithm API allows you to submit long-running graph algorithms as asynchronous jobs and track their progress. + +### 6.2.1 Submit an Algorithm Job + +#### 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 + +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](./task) to monitor the job. + +### 6.2.2 Monitor 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.2.3 Retrieve Algorithm Results + +The response body is algorithm-specific. Some algorithms return JSON directly, while others also write results back to vertex properties. + +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)"} +``` + +### 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. Review Comment: Vermeer is described elsewhere in this repo as the in-memory OLAP engine, while HugeGraph-Computer is the distributed one. Calling Vermeer a choice for "distributed computation" here is inaccurate and points readers to the wrong tool for scaling guidance. ########## content/en/docs/clients/restful-api/algorithm.md: ########## @@ -0,0 +1,111 @@ +--- +title: "Algorithm API" +linkTitle: "Algorithm" +weight: 12.5 +description: "Algorithm Job REST API: Submit and monitor asynchronous graph algorithm jobs." +--- + +## 6.2 Algorithm + +The Algorithm API allows you to submit long-running graph algorithms as asynchronous jobs and track their progress. + +### 6.2.1 Submit an Algorithm Job + +#### 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} +``` Review Comment: This page introduces a legacy `/graphs/{graph}` submission endpoint here, but the rest of the workflow only shows graphspace-based URLs. Users on 1.5.x-style deployments will be able to submit the job and then immediately hit the wrong paths for task polling/result queries unless the legacy task/vertex endpoints are documented too. ########## content/en/docs/clients/restful-api/algorithm.md: ########## @@ -0,0 +1,111 @@ +--- +title: "Algorithm API" +linkTitle: "Algorithm" +weight: 12.5 +description: "Algorithm Job REST API: Submit and monitor asynchronous graph algorithm jobs." +--- + +## 6.2 Algorithm + +The Algorithm API allows you to submit long-running graph algorithms as asynchronous jobs and track their progress. + +### 6.2.1 Submit an Algorithm Job Review Comment: This page is numbered as section 6.2, but `graphs.md` already uses 6.2 for the Conf subsection and `task.md` starts at 7.1. Reusing 6.2 here makes the REST API numbering inconsistent and will confuse cross-references and readers navigating the manual. ########## content/cn/docs/clients/restful-api/algorithm.md: ########## @@ -0,0 +1,111 @@ +--- +title: "算法 API" +linkTitle: "算法" +weight: 12.5 +description: "算法任务 REST API：提交和监控异步图算法任务。" +--- + +## 6.2 算法 + +算法 API 允许提交长时间运行的图算法作为异步任务并跟踪其进度。 + +### 6.2.1 提交算法任务 Review Comment: This page is numbered as section 6.2, but `graphs.md` already uses 6.2 for the Conf subsection and `task.md` starts at 7.1. Reusing 6.2 here makes the REST API numbering inconsistent and will confuse cross-references and readers navigating the manual. ########## content/cn/docs/clients/restful-api/algorithm.md: ########## @@ -0,0 +1,111 @@ +--- +title: "算法 API" +linkTitle: "算法" +weight: 12.5 +description: "算法任务 REST API：提交和监控异步图算法任务。" +--- + +## 6.2 算法 + +算法 API 允许提交长时间运行的图算法作为异步任务并跟踪其进度。 + +### 6.2.1 提交算法任务 + +#### 方法与 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} +``` Review Comment: This page introduces a legacy `/graphs/{graph}` submission endpoint here, but the rest of the workflow only shows graphspace-based URLs. Users on 1.5.x-style deployments will be able to submit the job and then immediately hit the wrong paths for task polling/result queries unless the legacy task/vertex endpoints are documented too. ########## content/cn/docs/clients/restful-api/algorithm.md: ########## @@ -0,0 +1,111 @@ +--- +title: "算法 API" +linkTitle: "算法" +weight: 12.5 +description: "算法任务 REST API：提交和监控异步图算法任务。" +--- + +## 6.2 算法 + +算法 API 允许提交长时间运行的图算法作为异步任务并跟踪其进度。 + +### 6.2.1 提交算法任务 + +#### 方法与 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} +``` + +#### 请求体 + +请求体因算法而异。常见参数包括： + +- `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](./task) 监控任务。 + +### 6.2.2 监控算法任务 + +使用 [任务 API](./task) 检查算法任务的状态： + +```bash +GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/tasks/{task_id} +``` + +### 6.2.3 检索算法结果 + +响应体是算法相关的。有些算法直接返回 JSON，有些算法还会把结果写回到顶点属性。 + +示例： + +- `page_rank` 会把排名写入 `r_rank` 顶点属性。 +- `lpa` 和 `weak_connected_component` 会把社区标签写入 `c_label` 顶点属性。 + +这些名称来自算法任务实现，可能与 HugeGraph 其他组件使用的属性名不同。 + +如果某个任务会写回顶点，请使用常规的 Vertex API，并按照算法更新的属性进行查询。 + +例如，要查找 PageRank 大于 0 的顶点，可以使用： + +```bash +GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/graph/vertices?properties={"r_rank":"P.gt(0)"} +``` + +### 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。 Review Comment: Vermeer is described elsewhere in this repo as the in-memory OLAP engine, while HugeGraph-Computer is the distributed one. Calling Vermeer a choice for "distributed computation" here is inaccurate and points readers to the wrong tool for scaling guidance. -- 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]
