diff --git a/content/cn/docs/SUMMARY.md b/content/cn/docs/SUMMARY.md index ab5e32bf9..9c3f27c0c 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) + * [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 new file mode 100644 index 000000000..3bf17442a --- /dev/null +++ b/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。 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..458d5c825 --- /dev/null +++ b/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.