bitflicker64 commented on code in PR #557: URL: https://github.com/apache/hugegraph-doc/pull/557#discussion_r4440456206
########## content/en/docs/quickstart/computing/hugegraph-vermeer.md: ########## @@ -95,701 +95,846 @@ cp config/master.ini config/worker.ini "$CONFIG_DIR/" ``` Keep master HTTP/gRPC listeners at `0.0.0.0:6688` and `0.0.0.0:6689`. The Compose example assigns `172.20.0.10` to master and `172.20.0.11` to worker; set these options in the copied `worker.ini`: - -```ini -[default] + +```ini +[default] http_peer=0.0.0.0:6788 grpc_peer=172.20.0.11:6789 master_peer=172.20.0.10:6689 run_mode=worker worker_group=$ -``` - +``` + This single-worker example uses literal `worker_group=$`, the general group used when no named group is bound. The repository template defaults to `worker_group=default`; if retaining that named group, bind it to the task space or graph before submitting tasks. For default space `$DEFAULT`, use: - + ```shell curl --fail --show-error -X POST \ 'http://localhost:6688/admin/workers/alloc/default/%24DEFAULT' ``` - + An `errcode=0` response confirms binding; with token authentication, also supply the authorization header. `master_peer` must reach master gRPC from the worker network. `grpc_peer` is both the listener and advertised worker address, so do not advertise `0.0.0.0`, which other containers cannot reach. Update these IPs when changing the subnet or addresses; each additional worker needs a unique, mutually reachable `grpc_peer`. 1. **Option 1: Docker Compose (Recommended)** Run from the Vermeer repository root. Modify existing `docker-compose.yaml` or use the following example. The repository file currently mounts all of `~/` as configuration and does not publish master HTTP; replace the mount and add the port mapping before starting: - -```yaml -services: - vermeer-master: - image: hugegraph/vermeer - container_name: vermeer-master - ports: + +```yaml +services: + vermeer-master: + image: hugegraph/vermeer + container_name: vermeer-master + ports: - "127.0.0.1:6688:6688" - volumes: + volumes: - /home/user/vermeer-config:/go/bin/config:ro - command: --env=master - networks: - vermeer_network: + command: --env=master + networks: + vermeer_network: ipv4_address: 172.20.0.10 # Static master address - - vermeer-worker: - image: hugegraph/vermeer - container_name: vermeer-worker - volumes: + + vermeer-worker: + image: hugegraph/vermeer + container_name: vermeer-worker + volumes: - /home/user/vermeer-config:/go/bin/config:ro - command: --env=worker - networks: - vermeer_network: + command: --env=worker + networks: + vermeer_network: ipv4_address: 172.20.0.11 # Static worker address - -networks: - vermeer_network: - driver: bridge - ipam: - config: + +networks: + vermeer_network: + driver: bridge + ipam: + config: - subnet: 172.20.0.0/24 # Change the subnet as needed -``` - +``` + Replace `/home/user/vermeer-config` with your actual absolute configuration directory. Changing the subnet or static IPs of `vermeer_network` also requires updating `grpc_peer` and `master_peer` in `worker.ini`. Do not use the default `grpc_peer=0.0.0.0:6789` as an advertised container address. - + Build and start from the project directory: - -```shell + +```shell # Build the image from the Vermeer root directory -docker build -t hugegraph/vermeer . - +docker build -t hugegraph/vermeer . + # Start from the Vermeer root directory -docker-compose up -d +docker-compose up -d # Or use the newer CLI: -# docker compose up -d -``` - +# docker compose up -d +``` + View logs / stop / remove: - -```shell -docker-compose logs -f -docker-compose down -``` - + +```shell +docker-compose logs -f +docker-compose down +``` + 2. **Option 2: Separate docker run Commands (Manual Network and Static IPs)** - + Set `CONFIG_DIR` to the prepared configuration directory, with `grpc_peer` and `master_peer` matching the static container addresses. Replace the example `CONFIG_DIR` with your actual absolute path. - -Build the image: - -```shell -docker build -t hugegraph/vermeer . -``` - + +Build the image: + +```shell +docker build -t hugegraph/vermeer . +``` + Create a custom bridge network (once): - -```shell -docker network create --driver bridge \ - --subnet 172.20.0.0/24 \ - vermeer_network -``` - + +```shell +docker network create --driver bridge \ + --subnet 172.20.0.0/24 \ + vermeer_network +``` + Run master (use your absolute `CONFIG_DIR` and adjust IPs as needed): - -```shell + +```shell CONFIG_DIR=/home/user/vermeer-config - -docker run -d \ - --name vermeer-master \ - --network vermeer_network --ip 172.20.0.10 \ + +docker run -d \ + --name vermeer-master \ + --network vermeer_network --ip 172.20.0.10 \ -p 127.0.0.1:6688:6688 \ -v ${CONFIG_DIR}:/go/bin/config:ro \ - hugegraph/vermeer \ - --env=master -``` - -Run worker: - -```shell -docker run -d \ - --name vermeer-worker \ - --network vermeer_network --ip 172.20.0.11 \ + hugegraph/vermeer \ + --env=master +``` + +Run worker: + +```shell +docker run -d \ + --name vermeer-worker \ + --network vermeer_network --ip 172.20.0.11 \ -v ${CONFIG_DIR}:/go/bin/config:ro \ - hugegraph/vermeer \ - --env=worker -``` - + hugegraph/vermeer \ + --env=worker +``` + View logs / stop / remove: - -```shell -docker logs -f vermeer-master -docker logs -f vermeer-worker - -docker stop vermeer-master vermeer-worker -docker rm vermeer-master vermeer-worker - + +```shell +docker logs -f vermeer-master +docker logs -f vermeer-worker + +docker stop vermeer-master vermeer-worker +docker rm vermeer-master vermeer-worker + # Delete the custom network if needed -docker network rm vermeer_network -``` - +docker network rm vermeer_network +``` + 3. **Option 3: Build from Source** - + Build following the [Vermeer README](https://github.com/apache/hugegraph-computer/tree/master/vermeer). - -```shell -go build -``` - + +```shell +go build +``` + Start from the Vermeer root directory with `./vermeer --env=master` and `./vermeer --env=worker01`. In `worker01.ini`, set `grpc_peer` to an address bindable locally and reachable by master and other workers; point `master_peer` to master gRPC. - + After starting master, check its HTTP port from the host: - -```shell -curl --fail --show-error http://localhost:6688/graphs -``` - + +```shell +curl --fail --show-error http://localhost:6688/graphs +``` + Expect HTTP 200 and JSON `errcode=0`. - -## 2. Task Creation REST API - -### 2.1 Introduction - + +### 1.3 Authentication, Token Tooling, and Deployment Credentials + +When `auth=token` is enabled in `master.ini` (or `-auth token` via CLI), protect the Master signing factor in a dedicated file (`0600`) instead of command-line +arguments. File-backed authentication uses **v2 HMAC-SHA256** Base58-encoded tokens with constant-time MAC verification, preventing legacy downgrade attacks. + +#### 1. Generating File-Backed Signing Factor + +Create a protected signing factor file before starting Master: + +```bash +umask 077 +openssl rand -hex 32 > config/token-factor +``` + +Set the environment variable `VERMEER_AUTH_TOKEN_FACTOR_FILE=/path/to/token-factor`, or set `auth_token_factor_file` in Master's `master.ini`. The environment +variable takes precedence over the INI file, and either file setting takes precedence over inline `auth_token_factor`. The file must contain one valid UTF-8 +line with at least 16 characters and cannot consist solely of whitespace. An invalid or unreadable file stops Master before opening network listeners (fails +closed), and it never falls back to inline or default factors. + +#### 2. Generating Auth Tokens with `/go/bin/vermeer-token` + +Vermeer container images bundle the native `/go/bin/vermeer-token` CLI utility (built from `cmd/vermeer-token`). It generates v2 Base58 tokens without +requiring a running Master or Kubernetes API access: + +```bash {tab="Docker CLI"} +docker run --rm --user "$(id -u):$(id -g)" -v "$PWD/config:/tokens" \ + --entrypoint /go/bin/vermeer-token \ + hugegraph/vermeer:latest -user admin -space '$DEFAULT' \ + -factor-file /tokens/token-factor -output-file /tokens/admin-token -i -quiet +``` + +```bash {tab="Go Source"} +go run ./cmd/vermeer-token -user admin -space '$DEFAULT' \ + -factor-file config/token-factor -output-file config/admin-token -i -quiet +``` + +CLI Parameters: +- `-user`: Username (default: `foo`). +- `-space`: Graph space name (default: `bar`; use `$DEFAULT` for system default graph space). +- `-factor-file`: Path to the signing factor file (required; inline factors are rejected). +- `-output-file`: Atomically writes the Base58 token with file mode `0600` without echoing secrets to stdout. +- `-quiet`: Suppresses informational logs and outputs only the token when `-output-file` is omitted. +- `-client`: Client identifier (default: `hg`). +- `-i`: Generates an immortal token that never expires (standard tokens expire after 24 hours). + +To authenticate HTTP requests, pass the generated token in the header: +```bash +curl -H "Authorization: Bearer <token>" http://localhost:6688/graphs +``` + +#### 3. Kubernetes Secret Password Files and Credential Isolation + +To integrate with Kubernetes Secrets without wrapping raw credentials in JSON, configure Worker with raw password files: + +- Set `VERMEER_HUGEGRAPH_USERNAME` and `VERMEER_HUGEGRAPH_PASSWORD_FILE` (or `hugegraph_username` and `hugegraph_password_file` in `worker.ini`). Both values + must be configured together; if either is set, a missing or unreadable file fails graph loading closed. +- Raw password file bytes are preserved exactly, including quotes, backslashes, spaces, and terminal newlines. +- When an explicit JSON credentials file is set (`VERMEER_HUGEGRAPH_CREDENTIALS_FILE` or `hugegraph_credentials_file`), it takes precedence over the raw pair. +- For PD authentication, mount `VERMEER_PD_PASSWORD_FILE` (or `pd_password_file` in INI). When deployment credentials are used, `VERMEER_PD_PEERS` (`pd_peers`) + is required to discover Schema exclusively through trusted PD endpoints. +- Secret credentials remain confined to deployment configuration and worker processes; they are never persisted in task metadata or returned in query APIs. +- Dial timeouts can be bounded with `grpc_dial_timeout` or `VERMEER_GRPC_DIAL_TIMEOUT` (default `5s`). + +## 2. Task Creation REST API + +### 2.1 Introduction + Submit a `load` task, wait for loading to finish, then submit a `compute` task. A loaded graph can support repeated computations and is not deleted after completion. Asynchronous APIs return creation results and task information, including ID, before completion; synchronous APIs wait for success or failure, so client and proxy HTTP timeouts must be sufficiently long. Query task states: `loaded` for successful loading, `complete` for successful computation, `error` for failure, and `canceled` for cancellation; other states remain waiting or running. Graphs loading or in an error state cannot be computed. Deletion requires a deletable graph state and no current usage. - + Available URLs: - + - Asynchronous: `POST http://master_ip:port/tasks/create`; read the ID from response `task.id`. - Synchronous: `POST http://master_ip:port/tasks/create/sync`; returns after the task ends. - Query task: `GET http://master_ip:port/task/{task_id}`. `errcode=0` indicates a successful query; inspect `task.state` for task status. - Set a client polling deadline for asynchronous jobs; reaching it stops client waiting without canceling the server task. -- Read retained results: `GET http://master_ip:port/tasks/value/{task_id}` (or `/api/v1/tasks/value/{id}`). - -Native clients submit `POST /api/v1/tasks/create` with `graph`, `task_type` (`load`, `reload` or `compute`), and a flat string-valued `params` map. -For computation, set `params["compute.algorithm"]`, not a top-level `algorithm`. -The response contains a native `task.id`; query it at `GET /api/v1/task/{id}` and read retained values at `GET /api/v1/tasks/value/{id}`. -These paths and positive IDs differ from Hubble's wrapper. -`POST /api/v1/tasks` does not submit work: after the task-method fix it returns HTTP 405 and `Allow: GET`; -older builds can return a misleading `{"code":200}` without creating a task. -See the [native API examples](https://github.com/apache/hugegraph-computer/blob/master/vermeer/README.md#api-overview). - -Vermeer Master HTTP follows Helm mode defaults: easy is NodePort, strict is ClusterIP; RPC and Worker ports remain internal. -Native UI admin uses the password in `<release>-vermeer-admin`. Automation APIs use service tokens in `Authorization: Bearer <token>`; + Set a client polling deadline for asynchronous jobs; reaching it stops client waiting without canceling the server task. +- Read retained results: `GET http://master_ip:port/tasks/value/{task_id}` (or `/api/v1/tasks/value/{id}`). +- Cluster health snapshot: `GET http://master_ip:port/api/v1/admin/cluster` (admin token required; see [Section 4](#4-cluster-monitoring-and-telemetry)). +- Worker availability probe: `GET http://master_ip:port/api/v1/workers/availability` (space-scoped availability check). + +Native clients submit `POST /api/v1/tasks/create` with `graph`, `task_type` (`load`, `reload` or `compute`), and a flat string-valued `params` map. +For computation, set `params["compute.algorithm"]`, not a top-level `algorithm`. +The response contains a native `task.id`; query it at `GET /api/v1/task/{id}` and read retained values at `GET /api/v1/tasks/value/{id}`. +These paths and positive IDs differ from Hubble's wrapper. +`POST /api/v1/tasks` does not submit work: after the task-method fix it returns HTTP 405 and `Allow: GET`; +older builds can return a misleading `{"code":200}` without creating a task. +See the [native API examples](https://github.com/apache/hugegraph-computer/blob/master/vermeer/README.md#api-overview). + +Vermeer Master HTTP follows Helm mode defaults: easy is NodePort, strict is ClusterIP; RPC and Worker ports remain internal. +Native UI admin uses the password in `<release>-vermeer-admin`. Automation APIs use service tokens in `Authorization: Bearer <token>`; UI admin password cannot be used as this token. Chart automatically configures service token for Hubble. - -### 2.2 Loading Graph Data - + +### 2.2 Loading Graph Data + The examples list common load parameters. Each loader reads its own keys; unused keys do not change behavior. - + Vermeer provides three loading methods: - + 1. Local files - + `load.vertex_files` and `load.edge_files` map worker address host portions to file paths read by those workers. With containers, mount data into the worker and use container paths. In the Compose example, mount a host data directory at worker `/data` (such as `- /host/data:/data:ro`) and use `172.20.0.11` from `grpc_peer` as the mapping key. Other deployments use the host portion of their advertised worker addresses. - + Obtain a dataset such as [Twitter-2010](https://snap.stanford.edu/data/twitter-2010.html); the first `twitter-2010.txt.gz` file is sufficient. **Request example:** - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "load", - "graph": "testdb", - "params": { - "load.parallel": "50", - "load.type": "local", + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "load", + "graph": "testdb", + "params": { + "load.parallel": "50", + "load.type": "local", "load.vertex_files": "{\"172.20.0.11\":\"/data/twitter-2010.v_[0,99]\"}", "load.edge_files": "{\"172.20.0.11\":\"/data/twitter-2010.e_[0,99]\"}", - "load.use_out_degree": "1", - "load.use_outedge": "1" - } -} -``` - + "load.use_out_degree": "1", + "load.use_outedge": "1" + } +} +``` + 2. HugeGraph - + **Request example:** - + Replace request addresses, graph name, and credentials with your actual connection settings. - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "load", - "graph": "testdb", - "params": { - "load.parallel": "50", - "load.type": "hugegraph", + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "load", + "graph": "testdb", + "params": { + "load.parallel": "50", + "load.type": "hugegraph", "load.hg_pd_peers": "[\"<pd-address-reachable-from-vermeer>:8686\"]", - "load.hugegraph_name": "DEFAULT/hugegraph2/g", - "load.hugegraph_username": "admin", - "load.hugegraph_password": "<your-password-here>", - "load.use_out_degree": "1", - "load.use_outedge": "1" - } -} -``` - + "load.hugegraph_name": "DEFAULT/hugegraph2/g", + "load.hugegraph_username": "admin", + "load.hugegraph_password": "<your-password-here>", + "load.use_out_degree": "1", + "load.use_outedge": "1" + } +} +``` + Vermeer master connects to PD through `load.hg_pd_peers` to look up partitions; workers read data from the returned Store addresses. These services must be reachable from the corresponding Vermeer hosts or containers. Inside Docker, `127.0.0.1` identifies the container itself, not the host or another container. - + 3. HDFS **Request example:** - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "load", - "graph": "testdb", - "params": { - "load.parallel": "50", - "load.type": "hdfs", - "load.hdfs_namenode": "name_node1:9000", - "load.hdfs_conf_path": "/path/to/conf", - "load.krb_realm": "EXAMPLE.COM", - "load.krb_name": "[email protected]", - "load.krb_keytab_path": "/path/to/keytab", - "load.krb_conf_path": "/path/to/krb5.conf", - "load.hdfs_use_krb": "1", - "load.vertex_files": "/data/graph/vertices", - "load.edge_files": "/data/graph/edges", - "load.use_out_degree": "1", - "load.use_outedge": "1" - } -} -``` - + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "load", + "graph": "testdb", + "params": { + "load.parallel": "50", + "load.type": "hdfs", + "load.hdfs_namenode": "name_node1:9000", + "load.hdfs_conf_path": "/path/to/conf", + "load.krb_realm": "EXAMPLE.COM", + "load.krb_name": "[email protected]", + "load.krb_keytab_path": "/path/to/keytab", + "load.krb_conf_path": "/path/to/krb5.conf", + "load.hdfs_use_krb": "1", + "load.vertex_files": "/data/graph/vertices", + "load.edge_files": "/data/graph/edges", + "load.use_out_degree": "1", + "load.use_outedge": "1" + } +} +``` + ### 2.3 Outputting Computation Results - + Current result writers support `local`, `hdfs`, and `hugegraph` through `output.type`; `none` disables output. Source retains an `afs` constant, but current master registers no AFS loader or writer. Set `output.need_statistics=1` to put statistics into task information; supported statistics operators depend on each algorithm implementation. - + The examples list common computation and output parameters; supported algorithm parameters depend on current Vermeer implementations. - -Request example: - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "compute", - "graph": "testdb", - "params": { - "compute.algorithm": "pagerank", - "compute.parallel": "10", - "compute.max_step": "10", - "output.type": "local", - "output.parallel": "1", - "output.file_path": "result/pagerank" - } -} -``` - -`output.type=local` writes to the executing worker's local filesystem. For containers, mount the output directory if the host needs to read results. - -### 2.4 Submit and Integrate via Hubble - -With Chart-managed native integration, `POST /api/v1.3/vermeer/task` is used to load or reload a graph, not for computation. -It accepts `graphspace`, `graph`, `task_type:"load"`, and optional loading tuning parameters. -Once the graph is loaded, submit the algorithm via the graph-level computation endpoint: - -```bash -curl -b hubble.cookies -X POST \ - 'http://localhost:8088/api/v1.3/graphspaces/DEFAULT/graphs/hugegraph/algorithms/vermeer' \ - -H 'Content-Type: application/json' \ - -d '{"params":{"compute.algorithm":"pagerank","compute.parallel":1,"compute.max_step":10,"pagerank.damping":0.85,"pagerank.diff_threshold":0.00001}}' -``` - -Parameters and example values come from the current Hubble PageRank form: - -| Parameter | Meaning | Example | -|---|---|---| -| `compute.algorithm` | Supported algorithm name | `pagerank` | -| `compute.parallel` | Computation parallelism | `1` | -| `compute.max_step` | Maximum iteration steps | `10` | -| `pagerank.damping` | PageRank damping factor | `0.85` | -| `pagerank.diff_threshold` | Convergence threshold | `0.00001` | - -Current Hubble accepts `pagerank`, `wcc`, `lpa`, `degree`, `closeness_centrality`, `betweenness_centrality`, `triangle_count`, `kcore`, and `sssp`. -Use the selected algorithm's form for its own parameters; PageRank keys do not apply to another algorithm. -The direct adapter accepts `compute.*`, the selected algorithm's `<algorithm>.*` keys and `output.need_statistics`. -Vermeer still validates the actual values. Hubble controls output storage and does not accept arbitrary output paths or Server credentials. - -The response contains `data.task_id` inside the Hubble response envelope. Preserve the returned sign: -Hubble maps native Vermeer task IDs to negative IDs. Poll the same graph's -`GET /api/v1.3/graphspaces/DEFAULT/graphs/hugegraph/async-tasks/{id}`; -read result pages through `GET .../async-tasks/{id}/values?cursor=0&limit=100` after successful completion. -Do not send that Hubble ID to Server's native `/tasks/{id}` endpoint. + +Request example: + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "compute", + "graph": "testdb", + "params": { + "compute.algorithm": "pagerank", + "compute.parallel": "10", + "compute.max_step": "10", + "output.type": "local", + "output.parallel": "1", + "output.file_path": "result/pagerank" + } +} +``` + +`output.type=local` writes to the executing worker's local filesystem. For containers, mount the output directory if the host needs to read results. + +### 2.4 Submit and Integrate via Hubble + +With Chart-managed native integration, `POST /api/v1.3/vermeer/task` is used to load or reload a graph, not for computation. +It accepts `graphspace`, `graph`, `task_type:"load"`, and optional loading tuning parameters. +Once the graph is loaded, submit the algorithm via the graph-level computation endpoint: + +```bash +curl -b hubble.cookies -X POST \ + 'http://localhost:8088/api/v1.3/graphspaces/DEFAULT/graphs/hugegraph/algorithms/vermeer' \ + -H 'Content-Type: application/json' \ + -d '{"params":{"compute.algorithm":"pagerank","compute.parallel":1,"compute.max_step":10,"pagerank.damping":0.85,"pagerank.diff_threshold":0.00001}}' +``` + +Parameters and example values come from the current Hubble PageRank form: + +| Parameter | Meaning | Example | +|---|---|---| +| `compute.algorithm` | Supported algorithm name | `pagerank` | +| `compute.parallel` | Computation parallelism | `1` | +| `compute.max_step` | Maximum iteration steps | `10` | +| `pagerank.damping` | PageRank damping factor | `0.85` | +| `pagerank.diff_threshold` | Convergence threshold | `0.00001` | + +Current Hubble accepts `pagerank`, `wcc`, `lpa`, `degree`, `closeness_centrality`, `betweenness_centrality`, `triangle_count`, `kcore`, and `sssp`. +Use the selected algorithm's form for its own parameters; PageRank keys do not apply to another algorithm. +The direct adapter accepts `compute.*`, the selected algorithm's `<algorithm>.*` keys and `output.need_statistics`. +Vermeer still validates the actual values. Hubble controls output storage and does not accept arbitrary output paths or Server credentials. + +The response contains `data.task_id` inside the Hubble response envelope. Preserve the returned sign: +Hubble maps native Vermeer task IDs to negative IDs. Poll the same graph's +`GET /api/v1.3/graphspaces/DEFAULT/graphs/hugegraph/async-tasks/{id}`; +read result pages through `GET .../async-tasks/{id}/values?cursor=0&limit=100` after successful completion. +Do not send that Hubble ID to Server's native `/tasks/{id}` endpoint. A graph state of `loaded` confirms loading only. An HTTP 400 on computation requires inspecting the exact rejected request and response. - -## 3. Supported Algorithms - -### 3.1 PageRank - -The PageRank algorithm, also known as the web ranking algorithm, is a technique used by search engines to calculate the relevance and importance of web pages (nodes) based on their mutual hyperlinks. - -- If a web page is linked to by many other web pages, it indicates that the web page is relatively important, and its PageRank value will be relatively high. -- If a web page with a high PageRank value links to other web pages, the PageRank value of the linked web pages will also increase accordingly. - -The PageRank algorithm is suitable for scenarios such as web page ranking and identifying key figures in social networks. - -Request example: - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "compute", - "graph": "testdb", - "params": { - "compute.algorithm": "pagerank", - "compute.parallel":"10", - "output.type":"local", - "output.parallel":"1", - "output.file_path":"result/pagerank", - "compute.max_step":"10" - } -} -``` - -### 3.2 WCC (Weakly Connected Components) - -The weakly connected components algorithm calculates all connected subgraphs in an undirected graph and outputs the weakly connected subgraph ID to which each vertex belongs, indicating the connectivity between points and distinguishing different connected communities. - -Request example: - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "compute", - "graph": "testdb", - "params": { - "compute.algorithm": "wcc", - "compute.parallel":"10", - "output.type":"local", - "output.parallel":"1", - "output.file_path":"result/wcc", - "compute.max_step":"10" - } -} -``` - -### 3.3 LPA (Label Propagation Algorithm) - -The label propagation algorithm is a graph clustering algorithm commonly used in social networks to discover potential communities. - -Request example: - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "compute", - "graph": "testdb", - "params": { - "compute.algorithm": "lpa", - "compute.parallel":"10", - "output.type":"local", - "output.parallel":"1", - "output.file_path":"result/lpa", - "compute.max_step":"10" - } -} -``` - -### 3.4 Degree Centrality - -The degree centrality algorithm calculates the degree centrality value of each node in the graph, supporting both undirected and directed graphs. Degree centrality is an important indicator of node importance; the more edges a node has with other nodes, the higher its degree centrality value, and the more important the node is in the graph. In an undirected graph, degree centrality is calculated based on edge information to count the number of times a node appears, resulting in the degree centrality value of the node. In a directed graph, it is based on the direction of the edges, filtering based on input or output-edge information to count the number of times a node appears, resulting in the in-degree or out-degree value of the node. It indicates the importance of each point, with more important points having higher degrees. - -Request example: - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "compute", - "graph": "testdb", - "params": { - "compute.algorithm": "degree", - "compute.parallel":"10", - "output.type":"local", - "output.parallel":"1", - "output.file_path":"result/degree", - "degree.direction":"both" - } -} -``` - -### 3.5 Closeness Centrality - -Closeness centrality is used to calculate the inverse of the shortest distance from a node to all other reachable nodes, accumulating and normalizing the value. Closeness centrality can be used to measure the time it takes for information to be transmitted from the node to other nodes. The larger the closeness centrality of a node, the closer its position in the graph is to the center, suitable for scenarios such as identifying key nodes in social networks. - -Request example: - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "compute", - "graph": "testdb", - "params": { - "compute.algorithm": "closeness_centrality", - "compute.parallel":"10", - "output.type":"local", - "output.parallel":"1", - "output.file_path":"result/closeness_centrality", - "closeness_centrality.sample_rate":"0.01" - } -} -``` - -### 3.6 Betweenness Centrality - -The betweenness centrality algorithm determines the value of a node as a "bridge" node; the larger the value, the more likely it is to be a necessary path between two points in the graph. Typical examples include mutual followers in social networks. It is suitable for measuring the degree of aggregation around a node in a community. - -Request example: - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "compute", - "graph": "testdb", - "params": { - "compute.algorithm": "betweenness_centrality", - "compute.parallel":"10", - "output.type":"local", - "output.parallel":"1", - "output.file_path":"result/betweenness_centrality", - "betweenness_centrality.sample_rate":"0.01" - } -} -``` - -### 3.7 Triangle Count - -The triangle count algorithm calculates the number of triangles passing through each vertex, suitable for calculating the relationships between users and whether the associations form triangles. The more triangles, the higher the degree of association between nodes in the graph, and the tighter the organizational relationship. In social networks, triangles indicate cohesive communities, and identifying triangles helps understand clustering and interconnections among individuals or groups in the network. In financial or transaction networks, the presence of triangles may indicate suspicious or fraudulent activities, and triangle counting can help identify transaction patterns that may require further investigation. - -The output result is the Triangle Count corresponding to each vertex, i.e., the number of triangles the vertex is part of. - -Note: This algorithm is for undirected graphs and ignores edge directions. - -Request example: - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "compute", - "graph": "testdb", - "params": { - "compute.algorithm": "triangle_count", - "compute.parallel":"10", - "output.type":"local", - "output.parallel":"1", - "output.file_path":"result/triangle_count" - } -} -``` - -### 3.8 K-Core - -The K-Core algorithm marks all vertices with a degree of K, suitable for graph pruning and finding the core part of the graph. - -Request example: - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "compute", - "graph": "testdb", - "params": { - "compute.algorithm": "kcore", - "compute.parallel":"10", - "output.type":"local", - "output.parallel":"1", - "output.file_path":"result/kcore", - "kcore.degree_k":"5" - } -} -``` - -### 3.9 SSSP (Single Source Shortest Path) - -The single source the shortest path algorithm calculates the shortest distance from one point to all other points. - -Request example: - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "compute", - "graph": "testdb", - "params": { - "compute.algorithm": "sssp", - "compute.parallel":"10", - "output.type":"local", - "output.parallel":"1", - "output.file_path":"result/degree", - "sssp.source":"tom" - } -} -``` - -### 3.10 KOUT - -Starting from a point, get the k-layer nodes of this point. - -Request example: - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "compute", - "graph": "testdb", - "params": { - "compute.algorithm": "kout", - "compute.parallel":"10", - "output.type":"local", - "output.parallel":"1", - "output.file_path":"result/kout", - "kout.source":"tom", - "compute.max_step":"6" - } -} -``` - -### 3.11 Louvain - -The Louvain algorithm is a community detection algorithm based on modularity. The basic idea is that nodes in the network try to traverse all neighbor community labels and choose the community label that maximizes the modularity increment. After maximizing modularity, each community is regarded as a new node, and the process is repeated until the modularity no longer increases. - -The distributed Louvain algorithm implemented on Vermeer is affected by factors such as node order and parallel computation. Due to the random traversal order of the Louvain algorithm, community compression also has a certain randomness, leading to different results in multiple executions. However, the overall trend will not change significantly. - -Request example: - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "compute", - "graph": "testdb", - "params": { - "compute.algorithm": "louvain", - "compute.parallel":"10", - "compute.max_step":"1000", - "louvain.threshold":"0.0000001", - "louvain.resolution":"1.0", - "louvain.step":"10", - "output.type":"local", - "output.parallel":"1", - "output.file_path":"result/louvain" - } - } -``` - -### 3.12 Jaccard Similarity Coefficient - -The Jaccard index, also known as the Jaccard similarity coefficient, is used to compare the similarity and diversity between finite sample sets. The larger the Jaccard coefficient value, the higher the similarity of the samples. It is used to calculate the Jaccard similarity coefficient between a given source point and all other points in the graph. - -Request example: - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "compute", - "graph": "testdb", - "params": { - "compute.algorithm": "jaccard", - "compute.parallel":"10", - "compute.max_step":"2", - "jaccard.source":"123", - "output.type":"local", - "output.parallel":"1", - "output.file_path":"result/jaccard" - } -} -``` - -### 3.13 Personalized PageRank - -The goal of personalized PageRank is to calculate the relevance of all nodes relative to user u. Starting from the node corresponding to user u, at each node, there is a probability of 1-d to stop walking and start again from u, or a probability of d to continue walking, randomly selecting a node from the nodes pointed to by the current node to walk down. It is used to calculate the personalized PageRank score starting from a given starting point, suitable for scenarios such as social recommendations. - -Since the calculation requires using out-degree, load.use_out_degree needs to be set to 1 when reading the graph. - -Request example: - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "compute", - "graph": "testdb", - "params": { - "compute.algorithm": "ppr", - "compute.parallel":"100", - "compute.max_step":"10", - "ppr.source":"123", - "ppr.damping":"0.85", - "ppr.diff_threshold":"0.00001", - "output.type":"local", - "output.parallel":"1", - "output.file_path":"result/ppr" - } -} -``` - -### 3.14 Global Kout - -Calculate the k-degree neighbors of all nodes in the graph (excluding themselves and 1~k-1 degree neighbors). Due to the severe memory expansion of the global kout algorithm, k is currently limited to 1 and 2. Additionally, the global kout algorithm supports filtering functions (parameters such as "compute.filter":"risk_level==1"), and the filtering condition is judged when calculating the k-degree. The final result set includes those that meet the filtering condition. The algorithm's final output is the number of neighbors that meet the condition. - -Request example: - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "compute", - "graph": "testdb", - "params": { - "compute.algorithm": "kout_all", - "compute.parallel":"10", - "output.type":"local", - "output.parallel":"10", - "output.file_path":"result/kout", - "compute.max_step":"2", - "compute.filter":"risk_level==1" - } -} -``` - -### 3.15 Clustering Coefficient - -The clustering coefficient represents the coefficient of the clustering degree of nodes in a graph. In real networks, especially in specific networks, nodes tend to establish a tightly organized relationship due to relatively high-density connection points. The clustering coefficient algorithm (Cluster Coefficient) is used to calculate the clustering degree of nodes in the graph. This algorithm is for local clustering coefficients. The local clustering coefficient can measure the clustering degree around each node in the graph. - -Request example: - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "compute", - "graph": "testdb", - "params": { - "compute.algorithm": "clustering_coefficient", - "compute.parallel":"100", - "compute.max_step":"10", - "output.type":"local", - "output.parallel":"1", - "output.file_path":"result/cc" - } -} -``` - -### 3.16 SCC (Strongly Connected Components) - -In the mathematical theory of directed graphs, if every vertex of a graph can be reached from any other point in the graph, the graph is said to be strongly connected. The parts of any directed graph that can achieve strong connectivity are called strongly connected components. It indicates the connectivity between points and distinguishes different connected communities. - -Request example: - -```javascript -POST http://localhost:6688/tasks/create -{ - "task_type": "compute", - "graph": "testdb", - "params": { - "compute.algorithm": "scc", - "compute.parallel":"10", - "output.type":"local", - "output.parallel":"1", - "output.file_path":"result/scc", - "compute.max_step":"200" - } -} - -``` - -> 🚧, further updates and improvements will be made at any time. Suggestions and feedback are welcome. + +## 3. Supported Algorithms + +### 3.1 PageRank + +The PageRank algorithm, also known as the web ranking algorithm, is a technique used by search engines to calculate the relevance and importance of web pages (nodes) based on their mutual hyperlinks. + +- If a web page is linked to by many other web pages, it indicates that the web page is relatively important, and its PageRank value will be relatively high. +- If a web page with a high PageRank value links to other web pages, the PageRank value of the linked web pages will also increase accordingly. + +The PageRank algorithm is suitable for scenarios such as web page ranking and identifying key figures in social networks. + +Request example: + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "compute", + "graph": "testdb", + "params": { + "compute.algorithm": "pagerank", + "compute.parallel":"10", + "output.type":"local", + "output.parallel":"1", + "output.file_path":"result/pagerank", + "compute.max_step":"10" + } +} +``` + +### 3.2 WCC (Weakly Connected Components) + +The weakly connected components algorithm calculates all connected subgraphs in an undirected graph and outputs the weakly connected subgraph ID to which each vertex belongs, indicating the connectivity between points and distinguishing different connected communities. + +Request example: + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "compute", + "graph": "testdb", + "params": { + "compute.algorithm": "wcc", + "compute.parallel":"10", + "output.type":"local", + "output.parallel":"1", + "output.file_path":"result/wcc", + "compute.max_step":"10" + } +} +``` + +### 3.3 LPA (Label Propagation Algorithm) + +The label propagation algorithm is a graph clustering algorithm commonly used in social networks to discover potential communities. + +Request example: + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "compute", + "graph": "testdb", + "params": { + "compute.algorithm": "lpa", + "compute.parallel":"10", + "output.type":"local", + "output.parallel":"1", + "output.file_path":"result/lpa", + "compute.max_step":"10" + } +} +``` + +### 3.4 Degree Centrality + +The degree centrality algorithm calculates the degree centrality value of each node in the graph, supporting both undirected and directed graphs. Degree centrality is an important indicator of node importance; the more edges a node has with other nodes, the higher its degree centrality value, and the more important the node is in the graph. In an undirected graph, degree centrality is calculated based on edge information to count the number of times a node appears, resulting in the degree centrality value of the node. In a directed graph, it is based on the direction of the edges, filtering based on input or output-edge information to count the number of times a node appears, resulting in the in-degree or out-degree value of the node. It indicates the importance of each point, with more important points having higher degrees. + +Request example: + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "compute", + "graph": "testdb", + "params": { + "compute.algorithm": "degree", + "compute.parallel":"10", + "output.type":"local", + "output.parallel":"1", + "output.file_path":"result/degree", + "degree.direction":"both" + } +} +``` + +### 3.5 Closeness Centrality + +Closeness centrality is used to calculate the inverse of the shortest distance from a node to all other reachable nodes, accumulating and normalizing the value. Closeness centrality can be used to measure the time it takes for information to be transmitted from the node to other nodes. The larger the closeness centrality of a node, the closer its position in the graph is to the center, suitable for scenarios such as identifying key nodes in social networks. + +Request example: + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "compute", + "graph": "testdb", + "params": { + "compute.algorithm": "closeness_centrality", + "compute.parallel":"10", + "output.type":"local", + "output.parallel":"1", + "output.file_path":"result/closeness_centrality", + "closeness_centrality.sample_rate":"0.01" + } +} +``` + +### 3.6 Betweenness Centrality + +The betweenness centrality algorithm determines the value of a node as a "bridge" node; the larger the value, the more likely it is to be a necessary path between two points in the graph. Typical examples include mutual followers in social networks. It is suitable for measuring the degree of aggregation around a node in a community. + +Request example: + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "compute", + "graph": "testdb", + "params": { + "compute.algorithm": "betweenness_centrality", + "compute.parallel":"10", + "output.type":"local", + "output.parallel":"1", + "output.file_path":"result/betweenness_centrality", + "betweenness_centrality.sample_rate":"0.01" + } +} +``` + +### 3.7 Triangle Count + +The triangle count algorithm calculates the number of triangles passing through each vertex, suitable for calculating the relationships between users and whether the associations form triangles. The more triangles, the higher the degree of association between nodes in the graph, and the tighter the organizational relationship. In social networks, triangles indicate cohesive communities, and identifying triangles helps understand clustering and interconnections among individuals or groups in the network. In financial or transaction networks, the presence of triangles may indicate suspicious or fraudulent activities, and triangle counting can help identify transaction patterns that may require further investigation. + +The output result is the Triangle Count corresponding to each vertex, i.e., the number of triangles the vertex is part of. + +Note: This algorithm is for undirected graphs and ignores edge directions. + +Request example: + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "compute", + "graph": "testdb", + "params": { + "compute.algorithm": "triangle_count", + "compute.parallel":"10", + "output.type":"local", + "output.parallel":"1", + "output.file_path":"result/triangle_count" + } +} +``` + +### 3.8 K-Core + +The K-Core algorithm marks all vertices with a degree of K, suitable for graph pruning and finding the core part of the graph. + +Request example: + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "compute", + "graph": "testdb", + "params": { + "compute.algorithm": "kcore", + "compute.parallel":"10", + "output.type":"local", + "output.parallel":"1", + "output.file_path":"result/kcore", + "kcore.degree_k":"5" + } +} +``` + +### 3.9 SSSP (Single Source Shortest Path) + +The single source the shortest path algorithm calculates the shortest distance from one point to all other points. + +Request example: + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "compute", + "graph": "testdb", + "params": { + "compute.algorithm": "sssp", + "compute.parallel":"10", + "output.type":"local", + "output.parallel":"1", + "output.file_path":"result/degree", + "sssp.source":"tom" + } +} +``` + +### 3.10 KOUT + +Starting from a point, get the k-layer nodes of this point. + +Request example: + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "compute", + "graph": "testdb", + "params": { + "compute.algorithm": "kout", + "compute.parallel":"10", + "output.type":"local", + "output.parallel":"1", + "output.file_path":"result/kout", + "kout.source":"tom", + "compute.max_step":"6" + } +} +``` + +### 3.11 Louvain + +The Louvain algorithm is a community detection algorithm based on modularity. The basic idea is that nodes in the network try to traverse all neighbor community labels and choose the community label that maximizes the modularity increment. After maximizing modularity, each community is regarded as a new node, and the process is repeated until the modularity no longer increases. + +The distributed Louvain algorithm implemented on Vermeer is affected by factors such as node order and parallel computation. Due to the random traversal order of the Louvain algorithm, community compression also has a certain randomness, leading to different results in multiple executions. However, the overall trend will not change significantly. + +Request example: + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "compute", + "graph": "testdb", + "params": { + "compute.algorithm": "louvain", + "compute.parallel":"10", + "compute.max_step":"1000", + "louvain.threshold":"0.0000001", + "louvain.resolution":"1.0", + "louvain.step":"10", + "output.type":"local", + "output.parallel":"1", + "output.file_path":"result/louvain" + } + } +``` + +### 3.12 Jaccard Similarity Coefficient + +The Jaccard index, also known as the Jaccard similarity coefficient, is used to compare the similarity and diversity between finite sample sets. The larger the Jaccard coefficient value, the higher the similarity of the samples. It is used to calculate the Jaccard similarity coefficient between a given source point and all other points in the graph. + +Request example: + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "compute", + "graph": "testdb", + "params": { + "compute.algorithm": "jaccard", + "compute.parallel":"10", + "compute.max_step":"2", + "jaccard.source":"123", + "output.type":"local", + "output.parallel":"1", + "output.file_path":"result/jaccard" + } +} +``` + +### 3.13 Personalized PageRank + +The goal of personalized PageRank is to calculate the relevance of all nodes relative to user u. Starting from the node corresponding to user u, at each node, there is a probability of 1-d to stop walking and start again from u, or a probability of d to continue walking, randomly selecting a node from the nodes pointed to by the current node to walk down. It is used to calculate the personalized PageRank score starting from a given starting point, suitable for scenarios such as social recommendations. + +Since the calculation requires using out-degree, load.use_out_degree needs to be set to 1 when reading the graph. + +Request example: + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "compute", + "graph": "testdb", + "params": { + "compute.algorithm": "ppr", + "compute.parallel":"100", + "compute.max_step":"10", + "ppr.source":"123", + "ppr.damping":"0.85", + "ppr.diff_threshold":"0.00001", + "output.type":"local", + "output.parallel":"1", + "output.file_path":"result/ppr" + } +} +``` + +### 3.14 Global Kout + +Calculate the k-degree neighbors of all nodes in the graph (excluding themselves and 1~k-1 degree neighbors). Due to the severe memory expansion of the global kout algorithm, k is currently limited to 1 and 2. Additionally, the global kout algorithm supports filtering functions (parameters such as "compute.filter":"risk_level==1"), and the filtering condition is judged when calculating the k-degree. The final result set includes those that meet the filtering condition. The algorithm's final output is the number of neighbors that meet the condition. + +Request example: + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "compute", + "graph": "testdb", + "params": { + "compute.algorithm": "kout_all", + "compute.parallel":"10", + "output.type":"local", + "output.parallel":"10", + "output.file_path":"result/kout", + "compute.max_step":"2", + "compute.filter":"risk_level==1" + } +} +``` + +### 3.15 Clustering Coefficient + +The clustering coefficient represents the coefficient of the clustering degree of nodes in a graph. In real networks, especially in specific networks, nodes tend to establish a tightly organized relationship due to relatively high-density connection points. The clustering coefficient algorithm (Cluster Coefficient) is used to calculate the clustering degree of nodes in the graph. This algorithm is for local clustering coefficients. The local clustering coefficient can measure the clustering degree around each node in the graph. + +Request example: + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "compute", + "graph": "testdb", + "params": { + "compute.algorithm": "clustering_coefficient", + "compute.parallel":"100", + "compute.max_step":"10", + "output.type":"local", + "output.parallel":"1", + "output.file_path":"result/cc" + } +} +``` + +### 3.16 SCC (Strongly Connected Components) + +In the mathematical theory of directed graphs, if every vertex of a graph can be reached from any other point in the graph, the graph is said to be strongly connected. The parts of any directed graph that can achieve strong connectivity are called strongly connected components. It indicates the connectivity between points and distinguishes different connected communities. + +Request example: + +```javascript +POST http://localhost:6688/tasks/create +{ + "task_type": "compute", + "graph": "testdb", + "params": { + "compute.algorithm": "scc", + "compute.parallel":"10", + "output.type":"local", + "output.parallel":"1", + "output.file_path":"result/scc", + "compute.max_step":"200" + } +} + +``` + +## 4. Cluster Monitoring and Telemetry + +Vermeer provides dedicated REST endpoints for operations dashboards (such as Apache HugeGraph Hubble) and cloud-native container orchestrators (such as +Kubernetes / Helm availability probes). + +### 4.1 Cluster Health Snapshot (`GET /api/v1/admin/cluster`) + +`GET /api/v1/admin/cluster` returns a read-only, versioned cluster health snapshot (`schema_version: 1`). In deployments where `auth=token` is enabled, this +endpoint requires an administrator token (`Authorization: Bearer <admin-token>`) and enforces the standard `/admin` authentication filters. + +#### Health and Readiness Semantics +- **`registered_workers` vs `ready_workers`**: Worker registration alone does not constitute readiness. A worker is considered ready only when it maintains an + active reverse gRPC connection to Master and 3 live task streams: `load`, `compute`, and `superstep`. +- **Status evaluation**: If there are zero registered workers or any registered worker fails readiness checks, the cluster status is marked as `DEGRADED` + with an explicit explanation in `reason` (such as `no_workers` or `worker_not_ready`). A fully operational cluster reports status `UP` (or `HEALTHY`). +- **Telemetry metrics**: Process-level telemetry is collected independently for Master and each Worker under `metrics`: + - `metrics.cpu_cores`: Consumed process CPU seconds per elapsed wall-clock second (can exceed 1.0 on multi-core architectures). + - `metrics.rss_bytes`: Resident Set Size in bytes (actual process resident memory, rather than host or container limits). + - `sample_window_seconds`: Elapsed time window over which CPU utilization was measured. + - `metric_status`: Resource sampling state (`ok`, `metrics_warming_up` during the initial measurement window, or `unsupported` on legacy nodes). +- **Isolation and bounded latency**: RPC metrics collection runs outside the Worker manager lock with an 800 ms timeout. A telemetry failure or timeout never + alters worker readiness or disrupts running computations. + +#### Example Request and Response + +```bash +curl -H "Authorization: Bearer <admin-token>" \ + http://localhost:6688/api/v1/admin/cluster +``` + +```json +{ + "schema_version": 1, + "observed_at": 1730419200000, + "status": "UP", + "registered_workers": 2, + "ready_workers": 2, + "master": { + "launch_time": "2026-11-01T08:00:00Z", + "status": "UP", + "ready": true, + "checks": { "grpc": true }, + "metrics": { + "cpu_cores": 0.15, + "rss_bytes": 134217728, + "sample_window_seconds": 10.0 + }, + "metric_status": "ok" Review Comment: R4 status at `723899ec`: **fixed**. `metric_status` is an object, the check keys match `http_cluster.go`, and the reason is `workers_not_ready`. A new port mix-up in the same example is reported in https://github.com/apache/hugegraph-doc/pull/557#discussion_r4440452149. ########## content/en/docs/clients/restful-api/traverser.md: ########## @@ -3266,3 +3267,78 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/traversers/count ##### 3.2.27.3 Use Cases Get the size of a multi-step neighborhood when only the number matters, so the vertices do not have to be serialized and transferred. + +#### 3.2.28 Same Neighbors Batch (POST) + +##### 3.2.28.1 Function Introduction + +Independently compute the common neighbors of multiple vertex pairs in a single batch HTTP request. +Unlike the GET `sameneighbors` endpoint which accepts two vertices, or the single-pair POST endpoint which computes one intersection across all vertices, +`sameneighborsbatch` accepts an array of pairs and evaluates each pair independently. + +###### Params + +- vertex_list: A list of vertex pairs, required. Each entry must contain exactly two non-null vertex IDs. Numeric IDs must be whole + numbers in the 64-bit integer range (`-9223372036854775808` to `9223372036854775807`). String and UUID formats are also supported. +- direction: Direction in which vertices expand outward (`OUT`, `IN`, `BOTH`). Optional, default is `BOTH`. +- label: Edge label filter. Optional, default matches all edge labels. +- max_degree: Maximum number of adjacent edges to traverse per vertex. Optional, default is `10000`. Must be positive or `-1` (unlimited). +- limit: Maximum number of common neighbors returned per pair. Optional, default is `10000000`. Must be positive up to `2147483647` or `-1`. + +##### 3.2.28.2 Usage Method + +###### Method & Url + +```text +POST http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/traversers/sameneighborsbatch +``` + +###### Request Body + +```json +{ + "vertex_list": [ + ["1:marko", "1:josh"], + ["1:peter", "1:josh"] + ], + "direction": "BOTH", + "label": "knows", + "max_degree": 10000, + "limit": 100 +} +``` + +###### Response Status + +```json +200 +``` + +###### Response Body + +The response contains `same_neighbors`, an array of arrays in input-pair order, and `measure` with traversal iteration counts and elapsed time: + +```json +{ + "same_neighbors": [ + [ + "2:lop" + ], + [] + ], + "measure": { + "vertex_iter_counter": 6, Review Comment: R4 status at `723899ec`: **fixed**. The example now uses `vertice_iterations`, `edge_iterations` and `cost(ns)`. ########## content/en/docs/quickstart/hugegraph/hugegraph-pd.md: ########## @@ -49,25 +51,27 @@ cd apache-hugegraph-incubating-1.7.0/apache-hugegraph-pd-incubating-1.7.0 #### 3.2 Compile from source -```bash -# 1. Clone the source code -git clone https://github.com/apache/hugegraph.git +1. **Clone the source code:** -# 2. Build the project -cd hugegraph -mvn clean install -DskipTests=true + ```bash + git clone https://github.com/apache/hugegraph.git + cd hugegraph + ``` -# 3. After a successful build, the PD directory and packages are located at -# hugegraph-pd/apache-hugegraph-pd-{version} (unpacked PD distribution) -# hugegraph-pd/apache-hugegraph-pd-{version}.tar.gz (PD only package, Linux build hosts only) -# target/apache-hugegraph-{version}.tar.gz (PD + Store + Server package) -``` +1. **Build the PD module:** -To build only the PD distribution and the modules it depends on: + ```bash + # Build only the PD distribution and its dependencies + mvn clean package -pl hugegraph-pd/hg-pd-dist -am -DskipTests + ``` -```bash -mvn clean package -pl hugegraph-pd/hg-pd-dist -am -DskipTests -``` +1. **Locate the distribution output:** + + ```bash + cd hugegraph-pd/apache-hugegraph-pd-* Review Comment: R4 status at `723899ec`: **fixed**. The command now uses `apache-hugegraph-pd-*/`. ########## scripts/audit-90d-commits-inventory.md: ########## @@ -0,0 +1,383 @@ +# 90-Day Commit History Audit & Documentation Gap Master Inventory + +> **Audit Period**: 2026-08-01 to 2026-11-01 (90 days relative to 2026-11-01) +> **Audited Repositories**: `apache/hugegraph`, `apache/hugegraph-toolchain`, `apache/hugegraph-ai`, `apache/hugegraph-computer`, `apache/hugegraph-doc` +> **Auditing Agent**: `worker_m4` (synthesizing surveys from `teamwork_explorer_survey_1`, `survey_2`, and `survey_3`) Review Comment: R4 status at `723899ec`: **fixed**. The file has been removed from the PR. ########## content/en/docs/quickstart/hugegraph-ai/hugegraph-llm-sdk.md: ########## @@ -0,0 +1,226 @@ +--- +title: "HugeGraph-LLM SDK Quick Start" Review Comment: R4 status at `723899ec`: **mostly fixed**. The page is now in `docs_nav.json` groups and sections, in both `version_routes.json` keys and in `SUMMARY.md`, and `versioning.py build/validate` passes for latest and 1.7. One gap remains in the precomputed `children_by_url` map; see https://github.com/apache/hugegraph-doc/pull/557#discussion_r4440452157. ########## content/en/docs/clients/client/hugegraph-client.md: ########## @@ -167,7 +556,7 @@ The constraint information that PropertyKey allows to define includes: name, dat |------------------------------------|------------------------------------------------| | userdata(String key, Object value) | The same key, the latter will cover the former | -##### 2.2.2 Create PropertyKey +##### 6.2.2 Create PropertyKey Review Comment: R4 status at `723899ec`: **still partly open**. Anchors from 2.x onward resolve, but `#1-hugegraph-client`, `#11-builder-options`, `#12-operation-entries` and `#5-simple-example`, plus their CN equivalents, are still not pinned on the merged page. -- 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]
