imbajin commented on code in PR #458: URL: https://github.com/apache/hugegraph-doc/pull/458#discussion_r3185899023
########## 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: Review Comment: The legacy fallback path here is misleading for the current server. `AlgorithmAPI` only exposes `graphspaces/{graphspace}/graphs/{graph}/jobs/algorithm/{name}`, so `/graphs/{graph}/jobs/algorithm/{name}` will 404 unless this is explicitly scoped to an older release branch. Consider removing the fallback or labeling it as historical-only. ########## 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: Review Comment: These parameter names do not match the server-side algorithm contract. The implementation validates keys like `times`, `sample`, `source_sample`, `depth`, and `degree`, not `max_iteration` or `sample_rate`. As written, the example can lead readers to send a request the API will reject. Please align this section with the actual request fields used by the algorithms. ########## 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 Review Comment: The supported-algorithms list would be much easier to use with a one-line description per item, or by linking each algorithm name to a reference like Wikipedia or the original paper. Right now the names alone are hard to interpret for first-time readers, especially for entries such as `lpa`, `louvain`, and `fusiform_similarity`. -- 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]
