Copilot commented on code in PR #458: URL: https://github.com/apache/hugegraph-doc/pull/458#discussion_r3170452927
########## 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` | Review Comment: The result property table is malformed because each row starts with `||` instead of `|`, which breaks Markdown table rendering. Please change it to standard table syntax with single leading/trailing pipes. ########## 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 提交算法任务 Review Comment: Same as EN: `weight: 11` duplicates `content/cn/docs/clients/restful-api/variable.md` (also weight 11), and the section numbering starts at `6.1` even though `Graphs API` already uses `### 6.1` (content/cn/docs/clients/restful-api/graphs.md:8). Please adjust weight and numbering to avoid collisions. ```suggestion weight: 12 description: "算法任务 REST API：提交和监控异步图算法任务。" --- ### 6.2 算法 算法 API 允许提交长时间运行的图算法作为异步任务并跟踪其进度。 #### 6.2.1 提交算法任务 ``` ########## 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) 检查算法任务的状态： Review Comment: In CN docs this link points to the non-localized `/docs/...` path. Please use `/cn/docs/clients/restful-api/task` (or a relative link like `./task`) so Chinese pages don’t redirect to the English site. ```suggestion 响应仅包含任务 ID。使用 [任务 API](./task) 监控任务。 #### 6.1.2 监控算法任务 使用 [任务 API](./task) 检查算法任务的状态： ``` ########## 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} Review Comment: The vertices query example uses `filter=properties.{property_name}`, but the Vertices API uses the `properties={...}` query parameter (see `vertex.md` “Get Vertices that Meet the Criteria”). This example should be updated to a valid format. ```suggestion GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/graph/vertices?properties={"{property_name}":"{property_value}"} ``` ########## 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) Review Comment: The CN SUMMARY navigation uses English labels for all RESTful API entries; adding `算法` here is inconsistent with the established pattern in this file. Consider naming it `Algorithm` (matching the surrounding entries) unless you intend to localize the entire SUMMARY list. ```suggestion * [Algorithm](clients/restful-api/algorithm) ``` ########## 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 Review Comment: `weight: 11` duplicates `content/en/docs/clients/restful-api/variable.md` (also weight 11), which can cause unstable ordering in Hugo menus. Also the section numbering starts at `6.1`, but `Graphs API` already uses `### 6.1` (content/en/docs/clients/restful-api/graphs.md:8), so this page should use a non-conflicting number (e.g., `6.2` and `6.2.x`). ########## 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} +``` Review Comment: The vertices query example uses `filter=properties.{property_name}`, but the documented Vertices API supports `properties={...}` (see `vertex.md` “Get Vertices that Meet the Criteria”). This example should be updated to a valid query parameter format (or explicitly recommend Gremlin if presence-only filtering isn’t supported). ########## 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。 Review Comment: In CN docs these links point to the non-localized `/docs/...` path. Please use `/cn/docs/quickstart/computing/hugegraph-computer` and `/cn/docs/quickstart/computing/hugegraph-vermeer` so navigation stays within the Chinese docs. ```suggestion 对于非常大的图（数百万+个顶点/边），考虑使用 [HugeGraph-Computer](/cn/docs/quickstart/computing/hugegraph-computer) 或 [HugeGraph-Vermeer](/cn/docs/quickstart/computing/hugegraph-vermeer) 进行分布式计算，而不是 REST API。 ``` ########## 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` | Review Comment: The result property table is malformed because rows start with `||` instead of `|`, which breaks Markdown rendering. Please switch to standard Markdown table syntax. -- 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]
