bitflicker64 commented on code in PR #557: URL: https://github.com/apache/hugegraph-doc/pull/557#discussion_r4440452161
########## content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md: ########## @@ -13,7 +13,7 @@ Ordinary graph queries connect directly to HugeGraph Server. Query generation, e ## Requirements -- Python 3.10 or later. A separate HugeGraph-LLM service must also meet that module's Python requirements. +- Python >= 3.12 (Python 3.12–3.14 supported). A separate HugeGraph-LLM service must also meet that module's Python requirements. Review Comment: **Minor: the Python requirement doesn't match the pinned version.** This line requires Python ≥ 3.12, but the examples pin `[email protected]`, which declares `requires-python = ">=3.10"`. Only the current 1.8.0 master needs ≥ 3.12. Please either state the requirement for the pinned 1.7.1 release, or pin the version this requirement applies to. The CN page has the same line. ########## content/en/docs/quickstart/computing/hugegraph-computer.md: ########## @@ -16,7 +16,11 @@ Computer reads graph data from HugeGraph or HDFS and writes results to either sy ## 2. Prerequisites and Connections -Building and running require JDK 11 or later; source builds also require Maven 3.5 or later. The PageRank example needs a running HugeGraph-Server with graph data, plus etcd reachable by the master and workers. +Building and running Computer (version 1.8.0+) require **JDK 17 or later** (for building, running, and cluster workers); source builds also require Review Comment: **Minor: the walkthrough no longer states the JDK requirement for the version it pins.** This line says 1.8.0+ requires JDK 17, and the earlier JDK 11 note is gone. The walkthrough below still downloads `VERSION=1.7.0` (around lines 46 and 49), so readers following it no longer see a JDK requirement for 1.7.0. Please keep the 1.7.0 note, or move the walkthrough to the version this line describes. ########## data/docs_nav.json: ########## @@ -1475,9 +1496,9 @@ "/docs/quickstart/hugegraph-ai/rest-api" Review Comment: **Minor: `children_by_url` (and `active_path_by_url`) still leave out the new SDK page.** `groups`, `sections` and the version routes now include `/docs/quickstart/hugegraph-ai/hugegraph-llm-sdk`, but the precomputed `children_by_url["/docs/quickstart/hugegraph-ai/"]` list above still has only the six older pages. A direct `scripts/hugo.sh build` or preview, without `versioning.py` re-materializing these maps, renders the HugeGraph-AI section index without the SDK. Release builds recompute the maps, so this only affects direct builds and previews. ########## content/en/docs/quickstart/computing/hugegraph-vermeer.md: ########## @@ -95,701 +95,825 @@ 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 +- Registration alone is not readiness. A Worker must be registered, connected to Master, and have `load`, `compute`, and `superstep` streams ready. +- Cluster status is `DEGRADED` for an unready Master, no Workers, or any unready Worker; aggregate reasons are `master_initializing` / `service_offline`, `no_workers`, or `workers_not_ready`. Otherwise status is `UP`. +- `metric_status` is an object with `availability` (`AVAILABLE`, `UNAVAILABLE`, or `UNSUPPORTED`), `observed_at`, and optional `reason`. +- Master checks are `http_ready`, `initialized`, and `service_online`; Worker checks are `registered`, `connection_ready`, and the three `*_stream_ready` fields. +- Worker telemetry uses one 800 ms aggregate deadline outside the Worker manager lock and does not affect readiness. + +#### 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": 1, + "ready_workers": 1, + "master": { + "id": "master", "name": "Vermeer Master", "role": "MASTER", + "grpc_peer": "127.0.0.1:6688", "version": "1.8.0", Review Comment: **Minor (new in this update): the gRPC ports in the example are wrong.** This example gives the master `grpc_peer` as `127.0.0.1:6688`, but `6688` is the master's HTTP port. Its gRPC peer is `6689` (`hugegraph-computer` `vermeer/config/master.ini:19-20`). The worker line (around line 901) uses `6689`, while this page's own config table gives worker gRPC as `6789`. Please use `6689` for the master and `6789` for the worker. The CN copy (around lines 881 and 889) has the same values. ########## content/en/docs/quickstart/hugegraph-ai/rest-api.md: ########## @@ -172,7 +173,40 @@ When `schema` is an existing graph name, also pass `client_config`, and make `cl } ``` -A successful response always contains `status` (always `succeeded`), `result.vertices`, `result.edges`, `warnings`, and `meta`. `meta` stays empty unless `include_meta` is `true`. +### Model Review and Repair (`review_options`) + +Providing `review_options` enables iterative model review and bounded schema repair for each text chunk: + +```json +{ + "texts": ["Alice works at Acme Corp.", "Bob works at Beta LLC."], + "schema": {...}, + "review_options": { + "max_reviews": 2, + "max_fixes": 1, + "max_workers": 4 + } +} +``` + +- `max_reviews` (default `2`, range `0`–`5`): Maximum review iterations per chunk. +- `max_fixes` (default `1`, range `0`–`3`): Maximum bounded repair attempts per chunk. +- `max_workers` (default `4`, range `1`–`8`): Number of chunks executed concurrently. +- Passing `{}` uses the defaults. Omitting `review_options` or setting it to `null` uses legacy extraction without review. + +### Response Format + +When `review_options` is omitted, `status` is always `succeeded` on HTTP 200. When `review_options` is enabled: +- The overall `status` reflects cumulative chunk results: `succeeded` (all chunks final), `partial` (some chunks final), or `failed` (no chunks final). +- Only `final` chunks are merged into top-level `result.vertices` and `result.edges`. +- The response includes `chunk_results` detailing each chunk's execution: + - `index`: 0-based chunk position. + - `status`: `final` (passed validation & review), `candidate` (passed validation; review budget exhausted), + `blocked` (schema constraints unresolved), or `failed` (exception or truncation). + - `graph`: The extracted sub-graph object (`vertices` and `edges`), or `null` on failure. + - `issues`: List of issues found during validation or review, including `path`, `message`, and optional `evidence`. + - `reason` and `stage`: Failure explanation and execution stage (`extract`, `review`, or `repair`). Review Comment: **Minor: the chunk `stage` list is incomplete.** The extraction runtime in `hugegraph-ai` (`extraction_runtime/review.py`) also emits `validate` and `prepare`, not just `extract`, `review` and `repair`. Clients that switch on this field would miss those stages. The CN page lists the same three values. ########## content/en/docs/clients/client/_index.md: ########## @@ -0,0 +1,33 @@ +--- +title: "Client SDKs" +linkTitle: "Client SDKs" +weight: 2 +description: "Overview and integration guides for official HugeGraph client SDKs (Java, Python, Go, and more)." +aliases: + - /docs/quickstart/client/ +--- + +HugeGraph provides official client SDKs for multiple programming languages, making it straightforward to connect to HugeGraph Server, manage schemas, +read and write vertices and edges, execute Gremlin traversals, and run graph algorithms. + +## Supported Clients + +- [HugeGraph Java Client](/docs/clients/client/hugegraph-client/) + + The primary Java SDK, offering an API style similar to Gremlin. It supports schema definitions, CRUD operations, Gremlin queries, Traverser algorithms, + and GraphSpace isolation. +- [HugeGraph Python Client](/docs/clients/client/hugegraph-client-python/) + + The official Python SDK (`pyhugegraph`), maintained in the HugeGraph-AI repository. It manages schemas, reads and writes graph data, + and executes Gremlin queries with first-class support for HugeGraph-LLM and HugeGraph-ML. +- [HugeGraph Go Client](/docs/clients/client/hugegraph-client-go/) + + The official Go SDK, supporting version checks, schema management (PropertyKey, VertexLabel, EdgeLabel), vertex operations, and Gremlin queries. +{.cards} + +## Selection Guide + +- **Java/Scala production services**: Use the **HugeGraph Java Client** for the most comprehensive feature set, connection pooling, and advanced Traverser algorithms. +- **AI, LLM, and data science workflows**: Use the **HugeGraph Python Client** for seamless integration with Python ML ecosystems, LangChain, and LlamaIndex. Review Comment: **Minor: the LlamaIndex integration claim is unsupported.** `hugegraph-ai` has no LlamaIndex dependency, and the only LangChain dependency is `langchain-text-splitters` in `hugegraph-llm`. Neither the Python client page nor the client itself documents such an integration. Please reword this to what the client actually provides. The CN copy (line 28) has the same claim. ########## content/en/docs/quickstart/toolchain/hugegraph-hubble.md: ########## @@ -218,23 +218,55 @@ Input footers show model generation time and query request time separately. Asyn ## Built-in algorithms: explore with parameter forms -Use **Built-in Algorithms** when you prefer a form to writing traversal code. Search for an algorithm and supply its parameters. -Neighbor exploration answers what surrounds a vertex, path algorithms connect two vertices, and similarity/ranking algorithms compare or select vertices. -Start with a known vertex ID and limit direction, edge labels, depth, and result size before attempting broader computation. +Hubble cleanly separates algorithm execution into two dedicated workflows: **OLTP online exploration** and **OLAP batch computing**. + +### OLTP online algorithms + +Use **Built-in Algorithms** when you prefer parameter forms to writing manual Gremlin traversals for real-time queries: +- **Neighbor exploration**: answers what surrounds a vertex (e.g. K-neighbor, K-hop). +- **Paths**: discovers connections between two vertices (e.g. shortest path, all paths). +- **Similarity & ranking**: compares or ranks vertices within local subgraphs. Forms provide parameter guidance and documentation links, and restore common parameters when navigating away and back. -Results use graph or algorithm-specific panels. Consult the help and documentation links beside the algorithm title for definitions and parameters. While the parameter form is focused, `Ctrl` / `Command` + `Enter` runs the current algorithm. -OLAP batch algorithms require external compute services such as Computer or Vermeer. -The two containers in this example provide online graph operations, not those compute services. - For example, select K-neighbor (GET) with `source=1:marko`, `max_depth=1`, and `limit=20`. After parameter validation, use the run button on the card or the form shortcut to explore one-hop neighbors.  {width="1600" height="1000"} +### Native Vermeer OLAP integration + +For large-scale, whole-graph analytical algorithms, Hubble integrates natively with the high-performance **Vermeer** graph computing engine. +Hubble prefers Vermeer for OLAP workloads by default, while Computer remains available as an opt-in alternative. + +#### Configuration in `hugegraph-hubble.properties` + +Enable direct Vermeer communication in `conf/hugegraph-hubble.properties`: + +```properties +# Direct Vermeer integration endpoint +vermeer.url=http://vermeer-master:8888 Review Comment: R4 status at `723899ec`: **fixed**. Both Vermeer addresses now use `:6688` in EN and CN, matching `master.ini`. -- 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]
