Quick Start

• 1: HugeGraph (OLTP)
  • 1.1: HugeGraph Server Quick Start
  • 1.2: HugeGraph-PD Quick Start
  • 1.3: HugeGraph-Store Quick Start
• 2: HugeGraph ToolChain
  • 2.1: Graph visualization
    • 2.1.1: Manage an HStore Cluster with Hubble
  • 2.2: Graph Visualization with Hubble: Standalone Quick Start
  • 2.3: Graph import
    • 2.3.1: Import Graph Data with SeaTunnel Sink
  • 2.4: HugeGraph-Loader Quick Start
  • 2.5: Graph export and migration
    • 2.5.1: Export and Migrate Graph Data with SeaTunnel Source
  • 2.6: Tools Quick Start
  • 2.7: HugeGraph-Spark-Connector Quick Start
• 3: HugeGraph-AI
  • 3.1: HugeGraph-LLM
  • 3.2: HugeGraph-ML
  • 3.3: HugeGraph-LLM Workflow
  • 3.4: Configuration Reference
  • 3.5: HugeGraph-LLM REST API
  • 3.6: Vermeer Python Client
• 4: HugeGraph Computing (OLAP)
  • 4.1: HugeGraph-Vermeer Quick Start
  • 4.2: HugeGraph-Computer Quick Start
  • 4.3: HugeGraph-Computer Configuration Reference
• 5: HugeGraph Client
  • 5.1: HugeGraph-Java-Client
  • 5.2: HugeGraph Python Client Quick Start
  • 5.3: HugeGraph Go Client Quick Start

1 - HugeGraph (OLTP)

This section covers the HugeGraph Server standalone quick start and the PD and Store guides needed for distributed deployments.

See the DeepWiki project overview. For installation, configuration, and runtime behavior, use the documentation and code for the relevant HugeGraph version.

Start with the Server standalone quick start, which distinguishes ASF 1.7.0 release packages from builds of master. HStore deployments also require PD and Store.

GitHub Access: https://github.com/apache/hugegraph

1.1 - HugeGraph Server Quick Start

1 HugeGraph Server Overview

apache/hugegraph is the main repository for the HugeGraph graph database. Its top-level modules include hugegraph-server, hugegraph-pd, and hugegraph-store. This page describes the hugegraph-server module and the service it runs.

The hugegraph-server module contains hugegraph-core, hugegraph-api, hugegraph-dist, and storage adapters. Core implements the property graph model, transactions, and TinkerPop interfaces. API provides the HTTP service and delegates client requests to Core. Graph data is stored in RocksDB (the default standalone backend), HStore (distributed), or HBase.

Naming: HugeGraph means the overall project or main repository, hugegraph-server is its Server module, and HugeGraphServer is the Java service class. Server below means the running graph database service.

flowchart TD
    A{Choose installation source}
    A -->|Release| R["HugeGraph 1.7.0 archive"]
    R --> V[Verify SHA-512]
    V --> X[Extract and use bundled configuration]
    A -->|Development| M["master source"]
    M --> B["mvn package -DskipTests"]
    B --> C[Check RocksDB configuration in conf/graphs]
    C --> I[bin/init-store.sh]
    I --> S["bin/start-hugegraph.sh -p true"]
    S --> Q["Request /versions and graph vertices"]

The map uses short labels for the repository modules described above. server, core, api, dist, pd, and store refer to the corresponding hugegraph- modules; dist packages the distribution.

---
markmap:
  spacingHorizontal: 40
---
# HugeGraph
## server
- core
- api
- dist
## pd
## store

2 Dependency for Building/Running

2.1 Install Java 11 (JDK 11)

The hugegraph-server module in HugeGraph 1.7.0 is compiled with Java 11. Running and building it from source require Java 11 or later.

Before continuing, run java -version to confirm your JDK version.

Java 8 is no longer supported starting from 1.7.0. bin/hugegraph-server.sh refuses to start on anything older than Java 11.

The security check is on by default and installs HugeSecurityManager, which needs Java 11 to 23. JDK 24 removed the Security Manager (JEP 486), so on Java 24 or later you must start the service with the check disabled: bin/start-hugegraph.sh -s false.

Building from source also needs Maven 3.5.0 or later.

3 Deploy

There are four ways to deploy the Server service:

• Docker container Quickly start a Server service for testing or development.
• ASF release archive Download a released tarball and verify it before installation.
• master source Build the development branch; its output is not an ASF release archive.
• Legacy one-click deployment (outdated) Reference for the older deployment workflow.

3.1 Use Docker container (Convenient for Test/Dev)

You can refer to the Docker deployment guide.

You can use docker run -itd --name=server -p 8080:8080 -e PASSWORD=xxx hugegraph/hugegraph:1.7.0 to quickly start a Server instance using the RocksDB backend.

Optional:

1. You can use docker exec -it server bash to enter the container for troubleshooting or other maintenance operations.
2. You can use docker run -itd --name=server -p 8080:8080 -e PRELOAD="true" hugegraph/hugegraph:1.7.0 to preload a built-in sample graph at startup. You can verify it through the RESTful API. See 5.1.4 for details.
3. You can use -e PASSWORD=xxx to enable authentication mode and set the admin password. See Config Authentication for details.

If you use Docker Desktop, you can set the options as follows:

Use docker compose to manage multiple HugeGraph services from one configuration. Four Compose files are available in the docker/ directory:

1cd hugegraph/docker
2# Keep the version aligned with the latest release, for example 1.x.0
3HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose.yml up -d --wait

The standalone topology publishes the Server on port 8080 and Hubble on 127.0.0.1:8088. HUGEGRAPH_VERSION selects the Server, PD, and Store image tags; Hubble is selected separately with HUBBLE_IMAGE.

The standalone docker-compose.yml example uses hugegraph/hugegraph:1.7.0; its docker/conf/hubble/standalone.properties is bundled in source. Compose reads the administrator password from HUGEGRAPH_ADMIN_PASSWORD and JWT secret from HUGEGRAPH_AUTH_TOKEN_SECRET, normally in docker/.env. A nonempty password enables authentication, automatically detected by Hubble. With docker run, use -e PASSWORD=xxx. Master HStore Compose files cannot be combined with 1.7.0 PD/Store/Server release images.

JWT version differences: Master-built Server maps HUGEGRAPH_AUTH_TOKEN_SECRET to HG_SERVER_AUTH_TOKEN_SECRET and writes startup configuration; preserve the secret across recreation. The 1.7.0 entrypoint handles older variables such as PASSWORD, ignoring HG_SERVER_AUTH_TOKEN_SECRET. To keep a stable JWT secret in 1.7.0, persist auth.token_secret in that version’s conf/graphs/hugegraph.properties. With a randomly generated default, do not assume issued JWTs survive Server restarts.

See docker/README.md for the full setup guide.

3.2 Download a Released Archive

This example uses HugeGraph 1.7.0. For other versions, confirm the release and filenames in the ASF download directory. A master source build is not a released binary.

1cd /path/to/downloads
2wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz
3wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz.sha512
4sha512sum -c apache-hugegraph-incubating-1.7.0.tar.gz.sha512
5tar zxf apache-hugegraph-incubating-1.7.0.tar.gz

Extract only after SHA-512 verification succeeds. You can also verify the PGP signature following Apache release procedures:

1wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz.asc
2wget https://downloads.apache.org/hugegraph/KEYS
3gpg --import KEYS
4gpg --verify apache-hugegraph-incubating-1.7.0.tar.gz.asc apache-hugegraph-incubating-1.7.0.tar.gz

Trust publisher keys only after verifying them through Apache project channels. Signature verification can complement SHA-512 checks.

3.3 Build from master Source

These commands build the development branch, not the 1.7.0 release.

Install wget or curl before building.

Download HugeGraph source:

1git clone --branch master https://github.com/apache/hugegraph.git

Compile and package:

1cd hugegraph
2# (Optional) use "-P stage" param if you build failed with the latest code(during pre-release period)
3mvn package -DskipTests -ntp

A successful build logs:

1[INFO] BUILD SUCCESS

The build creates an aggregate master archive under repository-root target/ (the current source version property is 1.7.0):

1target/apache-hugegraph-1.7.0.tar.gz

The filename version comes from source revision; it does not make the build an ASF release artifact. The build also creates repository-root apache-hugegraph-1.7.0/, containing a Server directory named by that module’s final.name, currently apache-hugegraph-server-1.7.0. If retaining only the archive, first run tar zxf target/apache-hugegraph-1.7.0.tar.gz, then enter the Server directory.

Default builds bundle rocksdb, hbase, and hstore modules, listed in backends within backend.properties in the hugegraph-dist JAR. For a RocksDB-only distribution, add -Drocksdb-only:

1mvn package -DskipTests -ntp -Drocksdb-only

1# download toolchain binary package, it includes loader + tool + hubble
2# please check the latest version (e.g. here is 1.7.0)
3wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-toolchain-incubating-1.7.0.tar.gz
4tar zxf *hugegraph-*.tar.gz
5
6# enter the tool's package
7cd *hugegraph*/*tool* 

1bin/hugegraph deploy -v {hugegraph-version} -p {install-path} [-u {download-path-prefix}]

4 Configuration

Server archives include conf/rest-server.properties, conf/gremlin-server.yaml, and conf/graphs/hugegraph.properties; source builds assemble them from hugegraph-server/hugegraph-dist/src/assembly/static/conf/. Edit them inside the extracted Server directory without a separate generation step. Defaults vary by release; the following defaults and startup behavior describe master.

For standalone RocksDB, confirm backend=rocksdb and serializer=binary in conf/graphs/hugegraph.properties. Normal Server initialization scans conf/graphs/ and loads local graphs without requiring graph.load_from_local_config=true. This option defaults to false and controls constructor preloading and rescanning on reload().

See the configuration guide and option reference for details.

5 Startup

5.1 Use a startup script to startup

Startup is divided into “first startup” and “non-first startup”. On the first startup, you need to initialize the backend database before starting the service.

If the service was stopped manually, or needs to be started again for any other reason, you can usually start it directly because the backend database is persistent.

When HugeGraphServer starts, it connects to the backend storage and checks its version information. If the backend has not been initialized, or if it was initialized with an incompatible version (for example, old-version data), HugeGraphServer will fail to start and report an error.

If you need to access HugeGraphServer externally, modify the restserver.url configuration item in rest-server.properties (the default is http://127.0.0.1:8080) and change it to the machine name or IP address.

Since the configuration (hugegraph.properties) and startup steps required by various backends are slightly different, the following will introduce the configuration and startup of each backend one by one.

5.1.1 Distributed Storage (HStore)

First deploy PD and Store; see the PD Quick Start and Store Quick Start.

1backend=hstore
2serializer=binary
3
4# PD RPC addresses, separated by commas
5pd.peers=127.0.0.1:8686,127.0.0.1:8687,127.0.0.1:8688
6pd.cluster=hg

 1# Simple example with authentication
 2gremlin.graph=org.apache.hugegraph.auth.HugeFactoryAuthProxy
 3
 4# Required HStore backend
 5backend=hstore
 6serializer=binary
 7store=hugegraph
 8
 9# pd config
10pd.peers=127.0.0.1:8686
11pd.cluster=hg

1usePD=true
2# Use cluster hg, matching pd.cluster in graph configuration
3cluster=hg
4# Server process PD addresses; replace with actual PD RPC addresses
5pd.peers=127.0.0.1:8686,127.0.0.1:8687,127.0.0.1:8688
6
7# Optional in local tests; authentication is mandatory in production
8# auth.authenticator=org.apache.hugegraph.auth.StandardAuthenticator

 1usePD=true
 2restserver.url=http://127.0.0.1:8081
 3gremlinserver.url=http://127.0.0.1:8181
 4pd.peers=127.0.0.1:8686
 5
 6rpc.server_host=127.0.0.1
 7rpc.server_port=8091
 8
 9server.id=server-1
10server.role=master

 1usePD=true
 2restserver.url=http://127.0.0.1:8082
 3gremlinserver.url=http://127.0.0.1:8182
 4pd.peers=127.0.0.1:8686
 5
 6rpc.server_host=127.0.0.1
 7rpc.server_port=8092
 8
 9server.id=server-2
10server.role=worker

1host: 127.0.0.1
2port: 8181

1host: 127.0.0.1
2port: 8182

1bin/start-hugegraph.sh

1curl http://localhost:8081/graphspaces/DEFAULT/graphs
2# Expected: {"graphs":["hugegraph"]}

1bin/stop-hugegraph.sh

1# Run from the HugeGraph repository root
2docker build -f hugegraph-pd/Dockerfile -t hugegraph/pd:local .
3docker build -f hugegraph-store/Dockerfile -t hugegraph/store:local .
4docker build -f hugegraph-server/Dockerfile-hstore -t hugegraph/server:local .
5
6cd docker

 1(
 2  set -eu
 3  command -v openssl >/dev/null
 4  jwt_secret="$(openssl rand -hex 32)"
 5  pd_secret="$(openssl rand -hex 24)"
 6  umask 077
 7  test ! -e .env || {
 8    echo ".env already exists; edit it instead of overwriting it" >&2
 9    exit 1
10  }
11  printf "HUGEGRAPH_ADMIN_PASSWORD='%s'\nHUGEGRAPH_AUTH_TOKEN_SECRET='%s'\nHG_PD_AUTH_SECRET_KEY='%s'\n" \
12    'replace-with-your-password' "${jwt_secret}" "${pd_secret}" > .env
13  HG_PD_AUTH_SECRET_KEY="${pd_secret}" ./set-hubble-pd-password.sh hstore
14  HG_PD_AUTH_SECRET_KEY="${pd_secret}" ./set-hubble-pd-password.sh hstore-ha
15)

1set -a
2. ./.env
3set +a
4HUGEGRAPH_VERSION=local docker compose \
5  -f docker-compose-3pd-3store-3server.yml \
6  up -d --wait pd0 pd1 pd2 store0 store1 store2 server0 server1 server2 hubble

1curl -fsS http://localhost:8080/versions
2curl -fsS -u "hg:${HG_PD_AUTH_SECRET_KEY:?Load .env first}" \
3  http://localhost:8620/v1/stores

5.1.2 RocksDB / ToplingDB

The minimal standalone flow below uses a master build and preloads sample data to verify graph reads and writes.

1. Check Java against the master build requirements.
2. Build master source; the commands below use its nested Server directory.
3. Confirm RocksDB configuration, then enter the build output’s nested Server directory.
4. Initialize storage, then start the service with sample data using the commands below.
5. Request /versions and sample graph vertices, and check the actual response contents.

Master conf/graphs/hugegraph.properties already sets backend=rocksdb and serializer=binary. Keep the defaults if using default data directories; otherwise check your backend and paths before initialization.

Initialize storage on first startup or after adding graph configuration under conf/graphs/:

1cd apache-hugegraph-1.7.0/apache-hugegraph-server-1.7.0
2bin/init-store.sh

Start Server and preload the built-in sample graph:

1bin/start-hugegraph.sh -p true

The startup script polls /graphs at configured restserver.url and exits nonzero on timeout or process failure. Check service version, then read sample vertices:

1curl -fsS http://127.0.0.1:8080/versions
2curl --compressed -fsS \
3  http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices

The first response should contain versions; the second should contain vertices with sample names such as marko and lop. A process check or HTTP status alone does not prove backend and business request health.

ToplingDB (Beta): A high-performance RocksDB alternative; see the ToplingDB Quick Start.

5.1.3 HBase

 1backend=hbase
 2serializer=hbase
 3
 4# hbase backend config
 5hbase.hosts=localhost
 6hbase.port=2181
 7# Note: recommend to modify the HBase partition number by the actual/env data amount & RS amount before init store
 8# it may influence the loading speed a lot
 9#hbase.enable_partition=true
10#hbase.vertex_partitions=10
11#hbase.edge_partitions=30

1cd *hugegraph-${version}
2bin/init-store.sh

1bin/start-hugegraph.sh
2Starting HugeGraphServer in daemon mode...
3Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK
4Started [pid 21614]

5.1.4 Create an example graph when startup

Pass the -p true argument when starting the script to enable preload, which creates a sample graph.

1bin/start-hugegraph.sh -p true
2Starting HugeGraphServer in daemon mode...
3Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK

And use the RESTful API to request HugeGraphServer and get the following result:

1> curl "http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices" | gunzip
2
3{"vertices":[{"id":"2:lop","label":"software","type":"vertex","properties":{"name":"lop","lang":"java","price":328}},{"id":"1:josh","label":"person","type":"vertex","properties":{"name":"josh","age":32,"city":"Beijing"}},{"id":"1:marko","label":"person","type":"vertex","properties":{"name":"marko","age":29,"city":"Beijing"}},{"id":"1:peter","label":"person","type":"vertex","properties":{"name":"peter","age":35,"city":"Shanghai"}},{"id":"1:vadas","label":"person","type":"vertex","properties":{"name":"vadas","age":27,"city":"Hongkong"}},{"id":"2:ripple","label":"software","type":"vertex","properties":{"name":"ripple","lang":"java","price":199}}]}

This indicates the successful creation of the sample graph.

5.1.5 Startup script options

bin/start-hugegraph.sh accepts the following options. Every one of them takes a value, so write -d false, not a bare -d.

bin/stop-hugegraph.sh accepts -m true|false (default true), which controls whether the cron monitor task is removed along with the service.

5.2 Use Docker to startup

In 3.1 Use Docker container, we introduced how to deploy hugegraph-server with Docker. You can also switch storage backends or preload a sample graph by setting the corresponding parameters.

5.2.1 Create an example graph when starting a server

Set the environment variable PRELOAD=true when starting Docker so that sample data is loaded during startup.

1. Use docker run

   Use docker run -itd --name=server -p 8080:8080 -e PRELOAD=true hugegraph/hugegraph:1.7.0

2. Use docker-compose

   Create a docker-compose.yml file like the following and set PRELOAD=true in the environment. example.groovy is a predefined script used to preload sample data. If needed, you can mount a new example.groovy script to change the preload data.

    1version: '3'
    2services:
    3  server:
    4    image: hugegraph/hugegraph:1.7.0
    5    container_name: server
    6    environment:
    7      - PRELOAD=true
    8      - PASSWORD=xxx
    9    volumes:
   10      - /path/to/yourscript:/hugegraph-server/scripts/example.groovy
   11    ports:
   12      - 8080:8080

   Use docker compose up -d to start the container.

And use the RESTful API to request HugeGraphServer and get the following result:

1> curl "http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices" | gunzip
2
3{"vertices":[{"id":"2:lop","label":"software","type":"vertex","properties":{"name":"lop","lang":"java","price":328}},{"id":"1:josh","label":"person","type":"vertex","properties":{"name":"josh","age":32,"city":"Beijing"}},{"id":"1:marko","label":"person","type":"vertex","properties":{"name":"marko","age":29,"city":"Beijing"}},{"id":"1:peter","label":"person","type":"vertex","properties":{"name":"peter","age":35,"city":"Shanghai"}},{"id":"1:vadas","label":"person","type":"vertex","properties":{"name":"vadas","age":27,"city":"Hongkong"}},{"id":"2:ripple","label":"software","type":"vertex","properties":{"name":"ripple","lang":"java","price":199}}]}

This indicates that the sample graph was created successfully.

6. Access server

6.1 Service startup status check

Use jps to see a service process

1jps
26475 HugeGraphServer

curl request RESTfulAPI

1curl -fsS http://127.0.0.1:8080/versions

HTTP 2xx with a JSON versions field confirms REST responsiveness. HugeGraphServer in jps confirms only process existence; verify backend health by preloading the sample graph and requesting vertices as above.

6.2 Request Server

The RESTful API of HugeGraphServer includes various types of resources, typically including graph, schema, gremlin, traverser and task.

• graph contains vertices、edges
• schema contains vertexlabels、 propertykeys、 edgelabels、indexlabels
• gremlin contains various Gremlin statements, such as g.v(), which can be executed synchronously or asynchronously
• traverser contains various advanced queries including shortest paths, intersections, N-step reachable neighbors, etc.
• task contains query and delete with asynchronous tasks

6.2.1 Get vertices and its related properties in hugegraph

1curl http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices

explanation

1. Server can compress vertex, edge, and other list responses. Use curl --compressed for automatic decompression:

   1curl --compressed -fsS "http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices"

2. The default listener is 127.0.0.1, inaccessible directly from other machines.

   1vim conf/rest-server.properties
   2
   3restserver.url=http://0.0.0.0:8080

response body:

 1{
 2    "vertices": [
 3        {
 4            "id": "2lop",
 5            "label": "software",
 6            "type": "vertex",
 7            "properties": {
 8                "price": [
 9                    {
10                        "id": "price",
11                        "value": 328
12                    }
13                ],
14                "name": [
15                    {
16                        "id": "name",
17                        "value": "lop"
18                    }
19                ],
20                "lang": [
21                    {
22                        "id": "lang",
23                        "value": "java"
24                    }
25                ]
26            }
27        },
28        {
29            "id": "1josh",
30            "label": "person",
31            "type": "vertex",
32            "properties": {
33                "name": [
34                    {
35                        "id": "name",
36                        "value": "josh"
37                    }
38                ],
39                "age": [
40                    {
41                        "id": "age",
42                        "value": 32
43                    }
44                ]
45            }
46        },
47        ...
48    ]
49}

For the detailed API, please refer to RESTful-API

You can also visit localhost:8080/swagger-ui/index.html to check the API.

When using Swagger UI to debug the API provided by HugeGraph, if HugeGraph Server turns on authentication mode, you can enter authentication information on the Swagger page.

Currently, HugeGraph supports setting authentication information in two forms: Basic and Bearer.

7 Stop Server

1cd apache-hugegraph-1.7.0/apache-hugegraph-server-1.7.0
2bin/stop-hugegraph.sh

8 Debug Server with IntelliJ IDEA

Please refer to Setup Server in IDEA

1.2 - HugeGraph-PD Quick Start

1 HugeGraph-PD Overview

HugeGraph-PD (Placement Driver) is the metadata management component of HugeGraph’s distributed version, responsible for managing the distribution of graph data and coordinating storage nodes. It plays a central role in distributed HugeGraph, maintaining cluster status and coordinating HugeGraph-Store storage nodes.

PD keeps cluster metadata in an embedded RocksDB store under pd.data-path and replicates it across PD nodes with Raft, so a 3-node or 5-node PD cluster keeps serving while a minority of nodes is down. On top of that it registers and activates Store nodes, allocates and rebalances partitions, tracks Store heartbeats, and answers service discovery queries from Store and Server.

PD listens on three ports:

2 Prerequisites

2.1 Requirements

• Operating System: Linux or macOS (Windows has not been fully tested)
• Java version: ≥ 11
• Maven version: ≥ 3.5.0

3 Deployment

There are two ways to deploy the HugeGraph-PD component:

• Method 1: Download the tar package
• Method 2: Compile from source

3.1 Download the tar package

Apache downloads currently provide the complete 1.7.0 binary bundle containing PD, Store, and Server, without a separate PD binary. Verify version, signatures, and SHA512 on the official download page. This historical incubating release retains incubating in archive and extracted directory names:

1# Historical release 1.7.0 retains incubating in filenames and directories
2wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz
3tar zxf apache-hugegraph-incubating-1.7.0.tar.gz
4cd apache-hugegraph-incubating-1.7.0/apache-hugegraph-pd-incubating-1.7.0

3.2 Compile from source

 1# 1. Clone the source code
 2git clone https://github.com/apache/hugegraph.git
 3
 4# 2. Build the project
 5cd hugegraph
 6mvn clean install -DskipTests=true
 7
 8# 3. After a successful build, the PD directory and packages are located at
 9#    hugegraph-pd/apache-hugegraph-pd-{version}          (unpacked PD distribution)
10#    hugegraph-pd/apache-hugegraph-pd-{version}.tar.gz   (PD only package, Linux build hosts only)
11#    target/apache-hugegraph-{version}.tar.gz            (PD + Store + Server package)

To build only the PD distribution and the modules it depends on:

1mvn clean package -pl hugegraph-pd/hg-pd-dist -am -DskipTests

The unpacked distribution contains just three directories: bin (start and stop scripts), conf (application.yml, application.yml.template, log4j2.xml, verify-license.json) and lib (the hg-pd-service jar).

3.3 Docker Deployment

HG_PD_* mappings and /v1/ready are features of current master; the Server 1.7.0 source tag lacks these Docker mappings and readiness API. The following examples require images built from current master and tagged local. For release 1.7.0 assets, use bundled configuration and version-specific instructions:

1# Run from the HugeGraph repository root
2docker build -f hugegraph-pd/Dockerfile -t hugegraph/pd:local .

To run master-built PD alone, first set a deployment-specific secret and replace example addresses with addresses reachable by the container:

 1export HG_PD_AUTH_SECRET_KEY="$(openssl rand -hex 24)"
 2docker run -d \
 3  -p 8620:8620 -p 8686:8686 -p 8610:8610 \
 4  -e HG_PD_GRPC_HOST=192.168.1.10 \
 5  -e HG_PD_RAFT_ADDRESS=192.168.1.10:8610 \
 6  -e HG_PD_RAFT_PEERS_LIST=192.168.1.10:8610 \
 7  -e HG_PD_INITIAL_STORE_LIST=192.168.1.20:8500 \
 8  -e HG_PD_AUTH_SECRET_KEY="$HG_PD_AUTH_SECRET_KEY" \
 9  -v /path/to/data:/hugegraph-pd/pd_data \
10  --name hugegraph-pd \
11  hugegraph/pd:local

The master entrypoint requires all five mandatory variables, builds SPRING_APPLICATION_JSON overrides, then starts PD. Other settings come from image conf/application.yml; JAVA_OPTS is passed to the JVM. Deprecated GRPC_HOST, RAFT_ADDRESS, RAFT_PEERS, and PD_INITIAL_STORE_LIST remain supported with warnings.

Docker HEALTHCHECK polls /v1/health every 15 seconds, confirming only REST listener liveness, not a Raft quorum. Compose uses the same liveness check; verify /v1/ready separately before starting Store. Containers run Java in the foreground and exit when Java exits; automatic restart requires a Docker restart policy. Inspect logs with docker logs <container-name>.

See the Store Docker section and docker/README.md for master Compose and the minimal topology. When starting the full topology with Hubble, first generate the untracked Hubble configuration described in that README.

4 Configuration

PD startup reads installation conf/application.yml. Match this file to the installed version: 1.7.0 configuration or master configuration. Master leaves auth.secret-key empty, causing protected REST calls to be rejected until configured. Startup does not read application.yml.template.

4.1 Configuration Reference

These tables were checked against hg-pd-dist configuration and Java defaults at Server master commit 2f827d6e8c9c62ae858f2fc122b3a192d015e2f4; they do not describe every 1.7.0 behavior. Use original tagged configuration with release binaries and master configuration with master builds.

gRPC and REST

application.yml.template also carries grpc.netty-server.max-inbound-message-size: 100MB, but PD sets the gRPC server’s inbound message limit to 1 GB in code, so that key has no effect.

Raft

PD core

Store management

Partitions

The initial partition count is derived from these two values and the size of pd.initial-store-list:

1initial partitions = store count * partition.store-max-shard-count / partition.default-shard-count

Discovery, license and metrics

Thread pools

4.2 Single-node configuration

For master-built distributions, start with conf/application.yml, adjust per-node gRPC/Raft addresses and data paths, and set auth.secret-key. The following values are for development and testing. One PD node provides no majority fault tolerance; partition.default-shard-count: 1 means one replica per partition.

 1grpc:
 2  host: 127.0.0.1
 3  port: 8686
 4server:
 5  port: 8620
 6raft:
 7  address: 127.0.0.1:8610
 8  peers-list: 127.0.0.1:8610
 9pd:
10  data-path: ./pd_data
11  initial-store-count: 1
12  initial-store-list: 127.0.0.1:8500
13partition:
14  default-shard-count: 1
15auth:
16  secret-key: replace-with-deployment-secret

Generate a deployment secret with openssl rand -hex 24; Docker supplies it through HG_PD_AUTH_SECRET_KEY. See REST API authentication for the different 1.7.0 behavior.

4.3 Three-node cluster configuration

For a production cluster run 3 or 5 PD nodes, an odd number so Raft always has a quorum. A 3-node cluster tolerates one node failure. raft.peers-list must list every node and must be byte-for-byte identical on all of them, while grpc.host and raft.address differ per node.

Node 1 (192.168.1.10):

 1grpc:
 2  host: 192.168.1.10
 3  port: 8686
 4server:
 5  port: 8620
 6raft:
 7  address: 192.168.1.10:8610
 8  peers-list: 192.168.1.10:8610,192.168.1.11:8610,192.168.1.12:8610
 9pd:
10  data-path: /data/pd
11  initial-store-count: 3
12  initial-store-list: 192.168.1.20:8500,192.168.1.21:8500,192.168.1.22:8500
13partition:
14  default-shard-count: 3

Node 2 (192.168.1.11) and node 3 (192.168.1.12) use the same file with grpc.host and raft.address changed to their own address:

 1# Node 2
 2grpc:
 3  host: 192.168.1.11
 4raft:
 5  address: 192.168.1.11:8610
 6  peers-list: 192.168.1.10:8610,192.168.1.11:8610,192.168.1.12:8610
 7
 8# Node 3
 9grpc:
10  host: 192.168.1.12
11raft:
12  address: 192.168.1.12:8610
13  peers-list: 192.168.1.10:8610,192.168.1.11:8610,192.168.1.12:8610

To put all three PD nodes on one machine for testing, give each node its own pd.data-path and its own ports, for example raft 8610/8611/8612, gRPC 8686/8687/8688 and REST 8620/8621/8622.

In Docker bridge networking the same configuration comes from environment variables and uses container hostnames instead of IP addresses:

 1# Share the same secret across PD nodes; inject it from private environment variables
 2HG_PD_AUTH_SECRET_KEY: ${HG_PD_AUTH_SECRET_KEY:?set HG_PD_AUTH_SECRET_KEY}
 3
 4# pd0
 5HG_PD_GRPC_HOST: pd0
 6HG_PD_RAFT_ADDRESS: pd0:8610
 7HG_PD_RAFT_PEERS_LIST: pd0:8610,pd1:8610,pd2:8610
 8HG_PD_INITIAL_STORE_LIST: store0:8500,store1:8500,store2:8500
 9HG_PD_INITIAL_STORE_COUNT: 3
10
11# pd1
12HG_PD_GRPC_HOST: pd1
13HG_PD_RAFT_ADDRESS: pd1:8610
14HG_PD_RAFT_PEERS_LIST: pd0:8610,pd1:8610,pd2:8610
15
16# pd2
17HG_PD_GRPC_HOST: pd2
18HG_PD_RAFT_ADDRESS: pd2:8610
19HG_PD_RAFT_PEERS_LIST: pd0:8610,pd1:8610,pd2:8610

5 Start and Stop

5.1 Start PD

In the PD installation directory, execute:

1./bin/start-hugegraph-pd.sh

The script requires a JDK of at least version 11 on PATH or in JAVA_HOME, and it exits without doing anything if it finds a Java process already using this installation’s conf directory.

Supported flags:

The -d flag controls daemon mode:

• -d true (default): run as a background daemon; the script returns immediately.
• -d false: run in foreground. The script execs Java, so the container or supervisor process IS Java. Use this when running under Docker or a process supervisor (systemd, supervisord) so crashes are detected and the service is restarted automatically.

Each flag also has an environment variable equivalent: DAEMON, GC_OPTION, USER_OPTION and OPEN_TELEMETRY. Setting JAVA_OPTIONS replaces the computed heap settings entirely; otherwise the script sizes the heap between 512 MB and 32 GB from available memory. Setting STDOUT_MODE=true leaves the JVM output on stdout instead of redirecting it to logs/hugegraph-pd-stdout.log, which is what the Docker image does.

After successful startup, you can see logs similar to the following in logs/hugegraph-pd-stdout.log:

1YYYY-mm-dd xx:xx:xx [main] [INFO] o.a.h.p.b.HugePDServer - Started HugePDServer in x.xxx seconds (JVM running for x.xxx)

The process id is written to bin/pid.

5.2 Stop PD

In the PD installation directory, execute:

1./bin/stop-hugegraph-pd.sh

The script reads bin/pid, sends the process a termination signal, waits up to 30 seconds for it to exit, and removes the pid file. If bin/pid is missing it reports that and exits successfully.

6 Startup Order in a Distributed Cluster

Start the components in this order:

1. All PD nodes. Form the Raft group and elect a leader. Check GET /v1/ready on each node; start Store only after HTTP 200 with ready:true. /v1/health checks REST listener liveness only.
2. All Store nodes. Register with PD; wait for /v1/stores to show every target Store as Up.
3. All Server nodes. Start after PD and Store are ready.

sequenceDiagram
    participant Operator
    participant PD
    participant Store
    participant Server
    Operator->>PD: GET /v1/ready (check each PD)
    PD-->>Operator: HTTP 200 and ready=true
    Operator->>Store: Start Store
    Store->>PD: gRPC registration and heartbeat
    Operator->>PD: GET /v1/stores (Basic authentication)
    PD-->>Operator: Every target Store is Up
    Operator->>Server: Start Server
    Server->>PD: gRPC partitions and discovery
    Server->>Store: gRPC graph data access

Master Compose waits on PD /v1/health through Store depends_on: condition: service_healthy, and on Store REST liveness before Server. Server also polls PD /v1/stores for an Up Store before starting. Therefore, docker compose up --wait does not replace PD Raft readiness and Store registration checks.

PD is also the last component to stop: shut down Server, then Store, then PD.

7 Verification

7.1 REST API Authentication

Current master requires HTTP Basic Authorization for all PD REST paths except /actuator/*, /v1/health, /v1/ready, and /v1/prom/targets/*. Username must be hg, store, hubble, or vermeer, and password must equal auth.secret-key. A missing secret or wrong password returns HTTP 401. Query Stores using the same secret configured at PD startup:

1{"status": -1, "error": "Unauthorized"}

1curl -u "store:${HG_PD_AUTH_SECRET_KEY:?Set the PD deployment secret first}" \
2  http://localhost:8620/v1/stores

bin/wait-storage.sh uses the same credentials through PD_AUTH_USER and PD_AUTH_PASSWORD. Release 1.7.0 checks only internal service usernames and does not compare passwords; do not apply this older behavior to master builds.

7.2 Health Checks

Unauthenticated GET /v1/health returns 200 with an empty body, confirming only PD REST listener startup:

1curl -i http://localhost:8620/v1/health

Spring Boot Actuator also provides a readable health response:

1curl http://localhost:8620/actuator/health

Actuator {"status":"UP"} does not confirm an available PD Raft leader. Master GET /v1/ready returns HTTP 200 with ready:true when the PD Raft node is active and sees a leader; otherwise it returns HTTP 503 with ready:false:

1curl -i http://localhost:8620/v1/ready

7.3 Cluster and member status

Check the PD members and which node is the Raft leader:

1curl -u "store:${HG_PD_AUTH_SECRET_KEY:?Set the PD deployment secret first}" \
2  http://localhost:8620/v1/members

The response carries pdList, the elected pdLeader, numOfService, numOfNormalService and a stateCountMap. In a healthy 3-node PD cluster numOfService and numOfNormalService are both 3 and exactly one member has role: "Leader".

GET /v1/cluster returns the same member list together with the Store list, graph list and overall cluster state, and GET / returns a short summary (leader address, cluster state, member count, store count, graph count, partition count).

7.4 Store status

You can also verify Store node status through the PD API:

1curl -u "store:${HG_PD_AUTH_SECRET_KEY:?Set the PD deployment secret first}" \
2  http://localhost:8620/v1/stores

If the response shows state as Up, the corresponding Store node is running normally. The example below shows a single Store node. In a healthy 3-node deployment, the storeId list should contain three IDs, and stateCountMap.Up, numOfService, and numOfNormalService should all be 3.

 1{
 2  "message": "OK",
 3  "data": {
 4    "stores": [
 5      {
 6        "storeId": 8319292642220586694,
 7        "address": "127.0.0.1:8500",
 8        "raftAddress": "127.0.0.1:8510",
 9        "version": "",
10        "state": "Up",
11        "deployPath": "/Users/{your_user_name}/hugegraph/apache-hugegraph-incubating-1.7.0/apache-hugegraph-store-incubating-1.7.0/lib/hg-store-node-1.7.0.jar",
12        "dataPath": "./storage",
13        "startTimeStamp": 1754027127969,
14        "registedTimeStamp": 1754027127969,
15        "lastHeartBeat": 1754027909444,
16        "capacity": 494384795648,
17        "available": 346535829504,
18        "partitionCount": 0,
19        "graphSize": 0,
20        "keyCount": 0,
21        "leaderCount": 0,
22        "serviceName": "127.0.0.1:8500-store",
23        "serviceVersion": "",
24        "serviceCreatedTimeStamp": 1754027127000,
25        "partitions": []
26      }
27    ],
28    "stateCountMap": {
29      "Up": 1
30    },
31    "numOfService": 1,
32    "numOfNormalService": 1
33  },
34  "status": 0
35}

7.5 Other REST endpoints

All paths below are relative to http://<pd-host>:8620 and need the Basic header from section 7.1 unless noted.

The two log endpoints take a time range as {"startTime": "...", "endTime": "..."}; yyyy-MM-dd HH:mm:ss and yyyy-MM-dd are among the accepted formats.

PD registers its own meters under the hg prefix, so /actuator/prometheus exposes hg_up, hg_graphs, hg_stores and hg_terms alongside the standard JVM metrics, plus per-graph partition and size meters once graphs exist.

1.3 - HugeGraph-Store Quick Start

1 HugeGraph-Store Overview

HugeGraph-Store is the storage node component of HugeGraph’s distributed version, responsible for actually storing and managing graph data. It works in conjunction with HugeGraph-PD to form HugeGraph’s distributed storage engine, providing high availability and horizontal scalability.

Each Store node keeps graph data in RocksDB and replicates it with Raft (JRaft): every partition is a separate Raft group, so a partition survives the loss of a minority of its replicas. Store nodes do not know about each other directly. They register with PD, receive their partition assignment from PD, and report state back over a heartbeat. HugeGraph-Server reaches Store over gRPC after looking up partition locations in PD.

2 Prerequisites

2.1 Requirements

• Operating System: Linux or macOS (Windows has not been fully tested)
• Java version: ≥ 11 (enforced by the build and re-checked by bin/start-hugegraph-store.sh)
• Maven version: ≥ 3.5.0
• Deploy HugeGraph-PD first for multi-node deployment

3 Deployment

There are two ways to deploy the HugeGraph-Store component:

• Method 1: Download the tar package
• Method 2: Compile from source

3.1 Download the tar package

Apache downloads currently provide the complete 1.7.0 binary bundle containing PD, Store, and Server, without a separate Store binary. Verify version, signatures, and SHA512 on the official download page. This historical incubating release retains incubating in archive and directory names:

1# Historical release 1.7.0 retains incubating in filenames and directories
2wget https://downloads.apache.org/hugegraph/1.7.0/apache-hugegraph-incubating-1.7.0.tar.gz
3tar zxf apache-hugegraph-incubating-1.7.0.tar.gz
4cd apache-hugegraph-incubating-1.7.0/apache-hugegraph-store-incubating-1.7.0

3.2 Compile from source

 1# 1. Clone the source code
 2git clone https://github.com/apache/hugegraph.git
 3
 4# 2. Build the project
 5cd hugegraph
 6mvn clean install -DskipTests=true
 7
 8# 3. After a successful build, the Store directory and complete distribution package are located at
 9#    hugegraph-store/apache-hugegraph-store-{version}
10#    target/apache-hugegraph-{version}.tar.gz

To build Store alone instead of the whole repository, build hugegraph-struct first, because Store depends on it:

1mvn install -pl hugegraph-struct -am -DskipTests
2mvn clean package -pl hugegraph-store/hg-store-dist -am -DskipTests

The assembled directory contains only bin/, conf/ and lib/hg-store-node-{version}.jar.

3.3 Docker Deployment

HG_STORE_* mappings are current master features, absent from Server tag 1.7.0. These Docker examples require PD, Store, and HStore Server images built from the same current master source with matching local tags:

1# Run from the HugeGraph repository root
2docker build -f hugegraph-pd/Dockerfile -t hugegraph/pd:local .
3docker build -f hugegraph-store/Dockerfile -t hugegraph/store:local .
4docker build -f hugegraph-server/Dockerfile-hstore -t hugegraph/server:local .

Before first startup, create .env in docker/ following the authentication environment instructions. The procedure uses umask 077 and refuses to overwrite existing files. Keep an existing .env and add missing entries. Never regenerate HG_PD_AUTH_SECRET_KEY for initialized data directories. Although .gitignore excludes this file, do not commit it. In every new shell, load the same file from docker/ before Compose or PD REST commands:

1# Run from the HugeGraph repository root
2cd docker
3set -a; . ./.env; set +a
4: "${HG_PD_AUTH_SECRET_KEY:?Set HG_PD_AUTH_SECRET_KEY in .env}"
5# Start PD, Store, and Server without optional Hubble
6HUGEGRAPH_VERSION=local HUGEGRAPH_PULL_POLICY=never \
7  docker compose -f docker-compose-hstore.yml \
8  up -d --wait pd store server

Load the same secret before subsequent restarts or PD REST calls; do not regenerate it for initialized directories. Explicitly include HUGEGRAPH_VERSION=local and HUGEGRAPH_PULL_POLICY=never in every Compose lifecycle command.

To start Hubble, use the topology-specific untracked configuration: minimal docker-compose-hstore.yml mounts conf/hubble/hstore.local.properties; HA docker-compose-3pd-3store-3server.yml mounts conf/hubble/hstore-ha.local.properties. The README initialization creates both files with the shared PD secret. If missing or requiring updates, load existing .env from docker/ and run:

1set -a; . ./.env; set +a
2./set-hubble-pd-password.sh hstore      # Minimal topology
3./set-hubble-pd-password.sh hstore-ha  # HA topology

Multi-node service names are pd0–pd2, store0–store2, and server0–server2. This master Compose file also requires matching locally built images; do not mix HUGEGRAPH_VERSION=1.7.0 release images with master Compose.

To run master-built Store alone, replace example addresses with actual routable Store and PD addresses:

1docker run -d \
2  -p 8520:8520 -p 8500:8500 -p 8510:8510 \
3  -e HG_STORE_PD_ADDRESS=192.168.1.10:8686 \
4  -e HG_STORE_GRPC_HOST=192.168.1.20 \
5  -e HG_STORE_RAFT_ADDRESS=192.168.1.20:8510 \
6  -v /path/to/storage:/hugegraph-store/storage \
7  --name hugegraph-store \
8  hugegraph/store:local

Current Master Docker Environment Variables:

The master entrypoint writes these values into SPRING_APPLICATION_JSON, overriding image conf/application.yml. Other options still come from that file and application-pd.yml; Java runs in the foreground. Deprecated PD_ADDRESS, GRPC_HOST, and RAFT_ADDRESS remain supported with warnings.

PD and Store Docker HEALTHCHECK use /v1/health, confirming only local REST responses. Compose depends_on uses the same startup gate; separately verify PD /v1/ready and Up Store state in /v1/stores. Store defaults to STDOUT_MODE=true; its Dockerfile declares only EXPOSE 8520, so publish gRPC 8500 and Raft 8510 separately if needed outside the Docker network.

4 Configuration

Store reads two files under conf/. Release 1.7.0 sources: application.yml, application-pd.yml. Master sources: application.yml, application-pd.yml. Master places RocksDB settings in the second file, included through spring.profiles.include: pd; startup selects application.yml.

• application.yml: Main PD address, ports, Raft, and data path settings.
• application-pd.yml: Included through spring.profiles.include: pd; RocksDB memory and Actuator exposure.

4.1 application.yml

The following tables were checked against distribution values and Java defaults at Server master commit 2f827d6e8c9c62ae858f2fc122b3a192d015e2f4. Use tagged configuration for release 1.7.0 without replacing it with another version’s files.

4.2 application-pd.yml

This file contains only rocksdb and Actuator exposure settings.

4.3 Configuration reference

“Master distribution value” comes from the two master files above. “Code default” is the fallback when a key is absent; rely on code defaults for options omitted from the distribution files.

Core

Raft

Storage and labels

RocksDB

Any other option defined in org/apache/hugegraph/rocksdb/access/RocksDBOptions.java can be added under the same rocksdb: block, for example rocksdb.max_background_jobs, rocksdb.level0_file_num_compaction_trigger or rocksdb.bloom_filter_bits_per_key.

Thread pools

gRPC callback queue (1.8.0)

Store uses an unbounded queue for gRPC callbacks so that a full queue does not discard cancellation or completion notifications and leave requests unfinished. You can keep thread.pool.grpc.queue in the configuration, but it no longer limits this queue.

thread.pool.grpc.core and thread.pool.grpc.max still configure the thread pool. Because callbacks can continue to queue, a backlog normally does not grow the pool from core to max; increasing max alone does not increase callback processing capacity.

Sustained overload can still grow the queue and increase memory usage. Limit client concurrency and size the scan and query worker pools for the node’s resources; do not rely on thread.pool.grpc.queue for load control. Version 1.7.0 still uses the configured gRPC queue capacity.

Query pushdown

Background jobs

Built-in PD mode

Only for single-node development and debugging, activated by app.fake-pd: true. The node then plays PD’s role itself and ignores pdserver.address.

Diagnostics

4.4 Per-node changes

For multi-node deployment, you need to modify the following configurations for each Store node:

1. grpc.host and grpc.port (the address other components dial)
2. raft.address (Raft protocol address)
3. server.port (REST port)
4. app.data-path (data storage path)

pdserver.address is the same on every node, it lists the whole PD cluster.

5 Start and Stop

5.1 Start Store

Ensure that the PD service is already started, then in the Store installation directory, execute:

1./bin/start-hugegraph-store.sh

The script accepts four flags:

Daemon mode:

• -d true (default): run as a background daemon. The script returns immediately and writes the Java pid to bin/pid.
• -d false: run in the foreground. The script execs Java, so the container or supervisor process is Java itself. Use this under Docker or a process supervisor (systemd, supervisord) so crashes are detected and the service is restarted automatically.

JVM memory, unless you set JAVA_OPTIONS yourself: -Xms512m, and -Xmx set to half the free memory, clamped to the 512 MB to 2048 MB range. The script also adds -XX:MetaspaceSize=256M, a heap dump on out-of-memory into logs/, and a rolling GC log at logs/gc.log. Production nodes normally need a much larger heap, so pass one explicitly, for example -j "-Xmx32g -Xms32g".

The script refuses to start if ulimit -n or ulimit -u is below 1024, and it preloads jemalloc on x86_64 and arm64 when the shared object can be downloaded and verified.

After successful startup, you can see logs similar to the following in logs/hugegraph-store-server.log:

1YYYY-mm-dd xx:xx:xx [main] [INFO] o.a.h.s.n.StoreNodeApplication - Started StoreNodeApplication in x.xxx seconds (JVM running for x.xxx)

5.2 Stop Store

In the Store installation directory, execute:

1./bin/stop-hugegraph-store.sh

The script reads bin/pid, signals that process, and waits up to 30 seconds for it to exit before removing the pid file. If bin/pid is missing it exits without doing anything.

5.3 Restart Store

1./bin/restart-hugegraph-store.sh

It sources the stop script and then the start script, and forwards the flags from section 5.1.

5.4 Startup order

1. All PD nodes first. Each Store’s grpc.host:grpc.port must appear in PD pd.initial-store-list, or the node remains Pending instead of Up, blocking partition allocation. On master, verify HTTP 200 with ready:true from every PD /v1/ready first; /v1/health is liveness only.
2. Store next. Registration retries while PD is unreachable, logging store heartbeat error: PD UNREACHABLE.
3. Server last. Every Store should report Up; partitions must be ready before opening or initializing graphs.

Master Compose uses depends_on: condition: service_healthy for local liveness, but PD and Store Docker checks only call /v1/health; they do not confirm Raft quorum or Store registration. Server waits for PD to report at least one Up Store. Operators should still check PD /v1/ready and /v1/stores.

6 Multi-Node Deployment Example

Below is a configuration example for a three-node deployment:

6.1 Three-Node Configuration Reference

• 3 PD nodes
  • raft ports: 8610, 8611, 8612
  • rpc ports: 8686, 8687, 8688
  • rest ports: 8620, 8621, 8622
• 3 Store nodes
  • raft ports: 8510, 8511, 8512
  • rpc ports: 8500, 8501, 8502
  • rest ports: 8520, 8521, 8522

6.2 Store Node Configuration

For the three Store nodes, the main configuration differences are as follows:

Node A:

1grpc:
2  port: 8500
3raft:
4  address: 127.0.0.1:8510
5server:
6  port: 8520
7app:
8  data-path: ./storage-a

Node B:

1grpc:
2  port: 8501
3raft:
4  address: 127.0.0.1:8511
5server:
6  port: 8521
7app:
8  data-path: ./storage-b

Node C:

1grpc:
2  port: 8502
3raft:
4  address: 127.0.0.1:8512
5server:
6  port: 8522
7app:
8  data-path: ./storage-c

All nodes should point to the same PD cluster:

1pdserver:
2  address: 127.0.0.1:8686,127.0.0.1:8687,127.0.0.1:8688

And every PD node should list all three Store gRPC addresses:

1pd:
2  initial-store-list: 127.0.0.1:8500,127.0.0.1:8501,127.0.0.1:8502

6.3 Docker Distributed Cluster Configuration

The distributed Store cluster definition is included in docker/docker-compose-3pd-3store-3server.yml. Each Store node gets its own hostname and environment variables:

 1# store0, published as 8500 (gRPC), 8510 (Raft), 8520 (REST)
 2HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686
 3HG_STORE_GRPC_HOST: store0
 4HG_STORE_GRPC_PORT: "8500"
 5HG_STORE_REST_PORT: "8520"
 6HG_STORE_RAFT_ADDRESS: store0:8510
 7HG_STORE_DATA_PATH: /hugegraph-store/storage
 8
 9# store1, published as 8501, 8511, 8521
10HG_STORE_GRPC_HOST: store1
11HG_STORE_RAFT_ADDRESS: store1:8510
12
13# store2, published as 8502, 8512, 8522
14HG_STORE_GRPC_HOST: store2
15HG_STORE_RAFT_ADDRESS: store2:8510

The container ports stay 8500/8510/8520 on every node, only the published host ports differ. The PD nodes set HG_PD_INITIAL_STORE_LIST: store0:8500,store1:8500,store2:8500 to match.

Store nodes start only after all PD nodes pass healthchecks (/v1/health), enforced via depends_on: condition: service_healthy.

To view runtime logs for a running Store container use docker logs <container-name> (e.g. docker logs hg-store0).

See docker/README.md for the full setup guide.

7 Verify Store Service

Confirm that the Store service is running properly:

1curl http://localhost:8520/actuator/health

Actuator {"status":"UP"} confirms local Store application health, without proving registration as Up in PD.

GET /v1/health is the lighter check used by the Docker image and the compose files. It answers HTTP 200 with an empty body, so use curl -fsS and check the exit code rather than the output:

1curl -fsS http://localhost:8520/v1/health && echo OK

7.1 Store REST endpoints

The Store node exposes these read-only endpoints on server.port:

Master Store configuration exposes all Actuator endpoints with management.endpoints.web.exposure.include: "*" and enables Prometheus. These endpoints lack PD REST Basic protection; restrict Store REST network access.

The node also serves maintenance endpoints that change state or run heavy work: PUT /-/state, GET /-/cleaner, GET /v1/partition/dump/{id}, GET /v1/partition/clean/{id}, POST /v1/compat?id=<partition>, GET /v1/arthasstart, POST /raft/options, and the /fix/* and /test/* groups. Use them only for troubleshooting, and keep the REST port off untrusted networks.

7.2 Check registration from PD

You can also check Store node status through the PD API:

1curl -u "store:${HG_PD_AUTH_SECRET_KEY:?Set the PD deployment secret first}" \
2  http://localhost:8620/v1/stores

For master builds, PD REST usernames must be hg, store, hubble, or vermeer, and the password must equal PD auth.secret-key. HG_PD_AUTH_SECRET_KEY configures PD and Server in Compose. /v1/health, /v1/ready, /actuator/*, and /v1/prom/targets/* require no authentication. Release 1.7.0 checks only usernames, without comparing passwords; do not use that old behavior for master builds.

If Store is configured successfully, the response should include status information for the current node, and state: "Up" means the node is running normally. A node stuck at Pending is usually missing from PD’s pd.initial-store-list.

The example below shows a single Store node. If all three nodes are configured correctly and running, the storeId list should contain three IDs, and stateCountMap.Up, numOfService, and numOfNormalService should all be 3.

 1{
 2  "message": "OK",
 3  "data": {
 4    "stores": [
 5      {
 6        "storeId": 8319292642220586694,
 7        "address": "127.0.0.1:8500",
 8        "raftAddress": "127.0.0.1:8510",
 9        "version": "",
10        "state": "Up",
11        "deployPath": "/Users/{your_user_name}/hugegraph/hugegraph-store/apache-hugegraph-store-{version}/lib/hg-store-node-{version}.jar",
12        "dataPath": "./storage",
13        "startTimeStamp": 1754027127969,
14        "registedTimeStamp": 1754027127969,
15        "lastHeartBeat": 1754027909444,
16        "capacity": 494384795648,
17        "available": 346535829504,
18        "partitionCount": 0,
19        "graphSize": 0,
20        "keyCount": 0,
21        "leaderCount": 0,
22        "serviceName": "127.0.0.1:8500-store",
23        "serviceVersion": "",
24        "serviceCreatedTimeStamp": 1754027127000,
25        "partitions": []
26      }
27    ],
28    "stateCountMap": {
29      "Up": 1
30    },
31    "numOfService": 1,
32    "numOfNormalService": 1
33  },
34  "status": 0
35}

7.3 Minimal Graph Read/Write Verification

After Store appears as Up in PD, start an HStore-backed Server connected to the same PD cluster. See the Server Quick Start. Once GET /versions responds and the default hugegraph graph is loaded, create a property key, vertex label, and vertex, then read it:

 1SERVER_URL=http://localhost:8080
 2GRAPH_URL="$SERVER_URL/graphspaces/DEFAULT/graphs/hugegraph"
 3
 4# Names must be unique within the graphspace; choose new names if they already exist
 5curl -fsS -X POST "$GRAPH_URL/schema/propertykeys" \
 6  -H 'Content-Type: application/json' \
 7  -d '{"name":"pd_store_demo_name","data_type":"TEXT","cardinality":"SINGLE","properties":[]}'
 8
 9curl -fsS -X POST "$GRAPH_URL/schema/vertexlabels" \
10  -H 'Content-Type: application/json' \
11  -d '{"name":"pd_store_demo_vertex","id_strategy":"CUSTOMIZE_STRING","properties":["pd_store_demo_name"],"primary_keys":[],"nullable_keys":[]}'
12
13curl -fsS -X POST "$GRAPH_URL/graph/vertices" \
14  -H 'Content-Type: application/json' \
15  -d '{"id":"pd-store-demo-1","label":"pd_store_demo_vertex","properties":{"pd_store_demo_name":"stored in HStore"}}'
16
17curl -fsS "$GRAPH_URL/graph/vertices/%22pd-store-demo-1%22"

The final response should contain vertex ID pd-store-demo-1 and property pd_store_demo_name. If Server authentication is enabled, add credentials to each request.

2 - HugeGraph ToolChain

HugeGraph Toolchain includes the Java and Go clients, Loader, Hubble, Tools, Spark Connector, and SeaTunnel Sink/Source. Choose an entry by the task you need to complete, then open the component guide for its configuration and commands.

Testing Guide: For running toolchain tests locally, please refer to HugeGraph Toolchain Local Testing Guide

DeepWiki provides real-time updated project documentation with more comprehensive and accurate content, suitable for quickly understanding the latest project information.

📖 https://deepwiki.com/apache/hugegraph-toolchain

Source repository: apache/hugegraph-toolchain

2.1 - Graph visualization

Hubble provides a Web interface for HugeGraph data, schema, queries, and imports. Start with a standalone deployment without PD, then read the distributed differences when needed.

• Hubble basics with standalone RocksDB: startup, sample graphs, modeling, imports, and queries.
• Hubble with an HStore cluster: PD discovery, GraphSpaces, and cluster operations.

2.1.1 - Manage an HStore Cluster with Hubble

This guide covers the differences between HStore + PD and standalone RocksDB. For modeling, importing data, and querying, see the Hubble standalone guide. This guide follows Toolchain master.

The main repository’s docker/docker-compose-hstore.yml already combines PD, Store, Server, and Hubble. Follow the adjacent Docker README to prepare .env and generated Hubble local configuration, then start it from docker/; do not maintain another deployment YAML. The settings below explain connection differences and do not replace the README’s PD credential and service-readiness requirements.

The screenshots use Hubble built from Toolchain 1.8.0 with Server, PD, and Store 1.7.0. Hubble currently returns the static value 3.0.0 from /about, which does not identify its build version. This pairing describes the screenshot environment; latest is mutable. Metrics and permission APIs vary by version.

Connect to a distributed cluster

Hubble still manages graph data through the Server graph API. In distributed mode, it discovers Servers through PD and collects cluster information from PD and Store. Hubble does not read or write graph data directly in Store.

For the official Compose deployment, prepare .env in the main repository’s docker/ directory following its README, then generate the Hubble configuration:

1set -a
2. ./.env
3set +a
4./set-hubble-pd-password.sh hstore

The script reads the loaded HG_PD_AUTH_SECRET_KEY and writes the PD operations password to the host file docker/conf/hubble/hstore.local.properties. Edit this generated file to customize connection or operations settings, preserving operations.pd.password so it matches PD’s secret. Do not replace it with the tracked .example template. Compose mounts it read-only at /hubble/conf/hugegraph-hubble.properties inside the container; do not edit it there. Do not commit the generated file or .env. Running the script again overwrites the generated file, so reapply custom settings afterward.

Start the services from the same docker/ directory and confirm Server registration and Store readiness:

1docker compose -f docker-compose-hstore.yml up -d --wait

For separately deployed services, follow the PD deployment guide and HStore deployment guide. A source or binary Hubble deployment instead uses the package’s conf/hugegraph-hubble.properties. These settings match the official minimal topology; use backend-reachable addresses for other deployments:

1pd.enabled=true
2cluster=hg
3pd.peers=pd:8686
4pd.server=pd:8620

Do not interchange ports 8686 and 8620, or retain 127.0.0.1 for connections between containers. The bundled file explicitly sets pd.enabled=false, while the Java fallback for a missing key is true; set it explicitly in either deployment. Restart source or binary Hubble deployments after configuration changes. For Compose, recreate the Hubble container from docker/ after editing or regenerating the host file so the read-only bind mount loads it again; retain the original project name and all -f arguments:

1docker compose -f docker-compose-hstore.yml up -d --force-recreate hubble

You do not enter a Server host and port for each graph in the UI.

Organize graphs and permissions with GraphSpaces

A GraphSpace groups graphs, Schema templates, and access permissions. For example, create sales and research spaces so each team can work with its own graphs. Modeling, importing, and querying within a space follow the standalone guide.

Create and adjust a GraphSpace

With Server authentication enabled, creating, editing, and deleting GraphSpaces require super administrator access. Start with a globally unique GraphSpace name, an optional display alias, and the maximum graph count. For example, use research as the API identifier and “Research_graph” as the display alias. The name cannot change after creation. The alias and description can change; aliases do not participate in URLs or permission matching. Choose GraphSpace administrators from existing accounts.

“Advanced deployment and resource limits” includes CPU and memory limits for graph query/write services and asynchronous compute tasks, plus the storage capacity limit. These are deployment and quota settings, not current usage or a promise to resize Docker containers when the form is saved. Defaults are 100 graphs, 64 CPU cores and 128 GB of memory for each of the graph and compute services, and 1000000 GB of storage. Keep the defaults for a container trial. Configure Kubernetes namespaces, Operator images, and algorithm images only for the corresponding deployment or compute use.

Select a space before opening a graph. Check the current graph after switching spaces, especially when spaces contain identically named graphs. The list reflects account access. If a space is missing, check membership permissions before creating more graphs.

Reuse Schema templates

User-defined Schema templates require PD mode and persist reusable Groovy Schema within a GraphSpace. When several business graphs share vertex labels, edge labels, and indexes, save the model as a template and select it when creating subsequent graphs. For example, a user template in research can be reused for new graphs in that space. After switching spaces, select a template belonging to the new space.

User templates differ from the built-in sample templates in the main guide: built-in templates help explore preset models, while user templates preserve your own models for future use. A template is not an import of data; loading sample data is a separate graph creation choice. With Server authentication enabled, creating a user template requires write access to its space. Updating or deleting it also requires ownership or the corresponding administrative permission. Anonymous mode does not enforce per-user permissions or template ownership checks. Standalone mode does not provide user template management.

Assign access to a GraphSpace

For account creation, login, and personal details, see the standalone guide. Distributed mode adds “Manage GraphSpace members” to assign permissions between existing accounts and selected spaces. Servers supporting permission presets provide these common choices:

An account may have different access in different spaces, such as read-write in research and read-only in sales. Accounts and space memberships are managed separately; removing a member does not delete the global account. After creating an account, continue directly to assigning space access. When changing an existing membership, check the selected space and preset and preserve permissions still needed in other spaces. Enabling pd.enabled grants no permissions; legacy custom roles on older Servers are not interchangeable with these presets. See Server authentication and authorization.

Locate problems through the cluster overview

The overview presents Server → PD → Store in one topology. Switch to the node list to filter by type, status, or name. PD Leader, online Store count, graphs, partitions, replicas, and data size help identify cluster scale and nodes requiring attention. Partitions and replicas describe data distribution. Data size is observed usage, distinct from a GraphSpace’s configured storage limit.

Start with cluster and source status, then inspect an affected node. UP indicates a successful collection from the source; DEGRADED indicates a cluster or partial source issue, and DOWN indicates that the corresponding probe failed. Graphs may remain queryable when topology is available but some metrics are missing. The UI distinguishes unsupported, unavailable, stale, and failed collections and includes observation times. An empty value is not zero, and an older value is not a current observation.

Read node details

The PD Leader and Store Leader partitions serve different purposes: PD coordinates cluster metadata, while a Store leads the respective data partition’s Raft group. Hubble displays upstream observations and does not replace a full Raft replica consistency check. Available metrics vary by component version.

With Server authentication enabled, cluster operations require a super administrator (ADMIN level). GraphSpace administrators and ordinary members do not inherit cluster access. Use container isolation, a trusted HTTPS entrypoint, Server authentication, and network allowlists; avoid publishing Hubble or component ports directly.

Configure operations access

Hubble’s backend uses the PD/Store operations credentials, separately from the Server account used to log in through the browser. For Compose, edit the generated host file docker/conf/hubble/hstore.local.properties; other deployments use the Hubble package configuration. The script-generated PD password must match the secret in .env. Configure the Store service account when Store authentication is enabled. Do not include passwords in documentation, screenshots, or committed configuration:

For example, when a containerized Store advertises store:8520, set:

1operations.store.allowed_targets=[http://store:8520]

For multiple nodes, list each trusted origin. Every entry must use http or https with an explicit port and no path, credentials, or wildcard, and must match the Store metric target returned by PD. Adding an origin to this list does not register or discover a node.

If topology is available but metrics are incomplete, check backend connectivity and authentication to PD REST, the Store REST/metric targets returned by PD, and their match with the allowlist. A partially available overview means some sources could not be collected; it does not imply that all graph APIs are unavailable.

2.2 - Graph Visualization with Hubble: Standalone Quick Start

Hubble is the HugeGraph Web management and graph visualization interface. Use one workspace to manage schema, import data, run queries, and switch between graph, table, and JSON results. This guide uses standalone RocksDB Server + Hubble, without PD or Store.

For HStore, read the shared operations here first, then follow the distributed supplement. This guide follows Toolchain master (currently 1.8.0); Docker latest is mutable, so check the actual running versions.

Start the standalone pair

Use the main repository’s docker/docker-compose.yml instead of writing another Compose file. It already combines RocksDB Server and Hubble, with networking, health checks, and data volumes. See the adjacent README for deployment details.

1git clone --branch master --single-branch --depth 1 https://github.com/apache/hugegraph.git
2cd hugegraph/docker

If you already have the main repository, enter its docker/ directory. Compose mounts conf/hubble/standalone.properties from that directory. It sets pd.enabled=false and server.direct_url=http://server:8080; both services communicate over one Docker network, without a Server address configured per graph. Do not download only the YAML and start it from another directory: relative configuration files may be missing.

Hubble defaults to host loopback port 8088; Server publishes 8080. For a trial on your machine only, change Server’s ports entry to 127.0.0.1:8080:8080 to avoid exposing the anonymous API to other machines.

Choose an unused project name for this trial and keep these variables in the same terminal. Restore this project name if you use another terminal.

1export HUGEGRAPH_VERSION=latest
2export HUBBLE_IMAGE=hugegraph/hubble:latest
3export HUBBLE_DEMO_PROJECT="hubble-demo-$(date +%Y%m%d-%H%M%S)"
4docker compose ls
5docker compose -p "$HUBBLE_DEMO_PROJECT" -f docker-compose.yml pull
6docker compose -p "$HUBBLE_DEMO_PROJECT" -f docker-compose.yml up -d --wait
7docker compose -p "$HUBBLE_DEMO_PROJECT" -f docker-compose.yml ps
8curl -fsS http://127.0.0.1:8080/versions

Once services are healthy, open http://127.0.0.1:8088. In a fresh directory without HUGEGRAPH_ADMIN_PASSWORD, Server allows anonymous access and Hubble opens the home page directly. For authentication, follow the Docker README to configure an administrator password and JWT secret in .env, then sign in with a Server account. Hubble has no separate account database. Personal and account-management pages depend on the authentication mode and your permissions. Do not overwrite an existing .env.

Use latest to try current features, and pin a published image version or digest for production. Images are convenience distributions; official release archives are on the download page. The algorithm and account screenshots use Hubble built from Toolchain 1.8.0 with Server 1.7.0. Hubble currently returns the static value 3.0.0 from /about, which does not identify the build version. This pairing describes those screenshots, not a fixed meaning of latest. Available controls depend on Server capabilities. Compose’s server-data and hubble-data retain graph data and Hubble metadata respectively. For further persistence and production settings, see the Server deployment guide.

Home: find the right starting point

Home groups the workspace into graph overview, data preparation, and graph queries. Use it to understand the workflow, then return to any section through the sidebar. The top graph selector determines the target of queries, schema operations, and async tasks; check the current graph after changing pages. Standalone mode has only the DEFAULT GraphSpace and needs no PD configuration.

Interface at a glance

Explore the graph overview, schema, and query workspaces in this gallery. Click an image to zoom; the operation sections below retain full-size screenshots for following each step.

• 

  Graph overview: select a graph and inspect sample data

• 

  Schema: inspect vertex labels, primary keys, and ID strategies

• 

  Graph query: run Gremlin and explore graph results

Graph Overview and details: get to know a graph

Select the default graph hugegraph in Graph Overview. The overview provides graph entry points and action menus. Graph details show schema and data statistics, with routes to modeling, data preparation, and queries. Statistics describe overall size; update them after importing or modifying data.

Load the People & Software Demo Graph from the graph’s More actions menu. Samples add their schema and missing elements without clearing existing data. Start with an empty graph to avoid conflicting schema names. The remaining examples explore the people and software in this graph.

Graph creation depends on Server capabilities. Its form accepts a name, optional alias, and schema or sample; it does not configure a Server host or account per graph. The connection comes from Hubble configuration. User-defined schema templates require PD mode; see the distributed supplement.

Schema modeling: define the shape of your data

Schema determines valid properties and relationships, vertex ID generation, and query indexes. Open the graph’s schema configuration. List view is useful for maintaining definitions; graph view helps explain how labels connect.

In the person/software sample, person generates IDs from the primary key name, with nullable age and city. software has custom numeric IDs, and created connects people to software. This matches the Loader example.

For a new model, define properties, vertex labels, edge labels, then indexes. Associated-property and index information help inspect dependencies. Schema deletion and index creation/rebuild may submit background tasks. Acceptance of an operation is only the first step; confirm its final status in Async Tasks.

GQL workspace: query and explore relationships

Open GQL Traversal and confirm hugegraph is selected. The workspace puts the editor and results together, with immediate or async execution, query favorites, and reusable execution history. Start with this Gremlin query:

1g.V().hasLabel('person').valueMap()

Inspect person properties in table or JSON view. To visualize the people-to-software relationships, run:

1g.V().hasLabel('person').outE('created').inV().path()

Graph results support 2D / 3D. Click a vertex or edge to inspect its ID, label, and properties; double-click a vertex to expand its neighbors. Layout, styling, and filtering help highlight relevant relationships, while export helps share results. Use New to create elements, or edit existing data when authorized. Layout, colors, and display limits only change presentation; adding/editing elements and Gremlin writes change Server data.

Use Ctrl / Command + Enter to execute. Immediate mode suits small explorations; submit long queries asynchronously and avoid returning an entire large graph. Cypher is available only when Server supports it. Text2GQL is currently a UI preview with no model or query service connected; it cannot generate executable queries.

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.

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.

Async Tasks: confirm background results

Async Tasks lists background work for the current graph, including async queries and some schema/index operations. Filter by task type and status, inspect IDs, creation times, and execution states, open successful query results, or expand failure information. Completed task records can be deleted where the interface permits. These tasks are separate from import execution history.

For example, submit g.V().count() asynchronously, confirm success in the list, then inspect the returned count. A successful submission means the request was accepted, not that computation or indexing has finished. Use task errors and Server logs together when diagnosing failures.

Data Source Management: prepare the input

A data source defines where data comes from and how to parse it, and can be referenced by import tasks. Hubble supports FILE, HDFS, JDBC, and Kafka, each with its own path, connection, or subscription settings. FILE is an easy starting point: upload a file, configure its format, delimiter, encoding, and header, and check column names before mapping. Hubble configuration controls upload limits and permitted extensions.

Save this UTF-8 file as people.csv for the person example:

1name,age,city
2docs_alice,28,Beijing
3docs_bob,32,Shanghai

Create a FILE data source and upload it. Select CSV (comma separation and UTF-8 by default), with column names name,age,city. Header, delimiter, and encoding belong to the data source, not mapping settings. The source fields must match the file.

Data Import: turn fields into a queryable graph

Data Import converts source rows into vertices and edges. Its four configuration sections identify the target, select fields, map them to the graph, and choose execution timing. Use the preceding data source to create a person import into DEFAULT / hugegraph:

person uses PRIMARY_KEY, so do not select a separate ID column. Custom ID strategies require an ID column; AUTOMATIC lets Server generate IDs, while PRIMARY_KEY derives them from mapped primary-key properties. Edge mappings need source/target fields that follow the corresponding vertex ID rules.

The task list manages configuration and execution entry points; execution history in task details shows each instance’s state, count, and errors. Periodic schedules and real-time Kafka tasks are also available; choose an execution mode compatible with the source. After completion, verify the result in the GQL workspace:

1g.V().hasLabel('person').has('name', within('docs_alice', 'docs_bob')).valueMap()

The result should include both new people. Import counts are not necessarily counts of newly created vertices: reruns may update existing elements, and header processing can affect reader counts. If the import fails, check source fields, numeric types, nullable properties, and target schema. Use Hubble for small trials and HugeGraph Loader for production bulk ingestion.

Profile and account permissions

Hubble uses Server authentication and accounts, with no separate user database. Anonymous mode hides Profile and Account Management. After authentication is enabled, Profile shows the current account’s details and permissions and allows changing your password. Editing details such as a nickname requires Server support for the personal-profile API. Changing a password ends the current session; sign in again with the new password.

Standalone account management

In standalone mode, the administrator can create, inspect, edit, delete, and batch-create accounts. Ordinary standalone accounts created through Hubble receive read, write, delete, and execute permissions across all graphs; they are not read-only or isolated to one graph. Configure finer resource permissions through Server authentication and authorization rather than relying on GraphSpace presets.

GraphSpace permissions in PD mode

With a Server supporting default-role APIs, global accounts and space access can be managed separately. The administrator manages global accounts; a space administrator manages members only within authorized spaces. Ordinary members do not receive account-management or operations entry points. The following presets are for PD mode, and are not universally editable on older or standalone Servers:

An account may have different permissions in different spaces. Select a space before adding an existing account or changing member permissions. Before replacing custom permissions with a preset, inspect the grants that need to be retained; complex permissions may not match a single preset. After changes, refresh permission context or sign in again and verify menus and space selection. Server still validates every request. Older Servers may hide or disable unsupported operations; a visible button alone does not establish resource authorization. See the distributed supplement for space management.

Operations: inspect the standalone Server

Standalone Operations provides Node Information for Server only, with no PD/Store nodes or cluster overview. Search nodes, filter health status, and open node details to inspect available version, system, JVM, and Server-backend metrics. When metrics are unavailable or stale, use collection state and the last successful observation time; a missing value is neither zero nor proof of health.

Anonymous mode can read operations information. With authentication enabled, operations are available only to administrators with the capability. This is an observation and diagnosis interface, not a start/stop or scaling console. The distributed supplement covers cluster overview and the PD/Store node hierarchy.

Keyboard shortcuts and graph interactions

Use the topbar shortcut-help button to see key bindings. Their scope differs: typing ? in an input does not trigger global help.

Diagnose connection and result issues

Configuration can affect displayed query size. gremlin.suffix_limit defaults to 250 and supplies .limit(N) appended to applicable Gremlin queries; it is not a universal hard limit. gremlin.vertex_degree_limit (100) and gremlin.edges_total_limit (500) constrain expansion. FILE uploads allow csv,txt by default, with 1 GB per file and 10 GB total. Override upload_file.* settings when needed.

Stop the trial or build from source

When finished, run this in the main repository’s docker/ directory:

1docker compose -p "${HUBBLE_DEMO_PROJECT:?}" -f docker-compose.yml down --volumes

This removes the project’s containers, network, named volumes, and anonymous volume, losing the sample data and Hubble import tasks. To retain data, omit --volumes when taking the deployment down and reuse the same project name when starting it again.

To obtain an exact master build, use JDK 11 and Maven. The Maven plugin installs the required Node/Yarn; you do not need to install them separately. These commands skip tests:

1git clone --branch master --single-branch https://github.com/apache/hugegraph-toolchain.git
2cd hugegraph-toolchain
3mvn install -pl hugegraph-client,hugegraph-loader -am -Dmaven.javadoc.skip=true -DskipTests -ntp
4cd hugegraph-hubble
5mvn package -Dmaven.javadoc.skip=true -DskipTests -ntp
6cd apache-hugegraph-hubble-*
7# Edit conf/hugegraph-hubble.properties with the correct Server URL
8bin/start-hubble.sh

The bundled configuration binds to localhost:8088. bin/stop-hubble.sh requests graceful shutdown before forcing termination on timeout. For development and testing, see the Toolchain local test guide.

2.3 - Graph import

Choose an import tool when you need to write file, database, or message data into HugeGraph. Use Loader for a direct import, SeaTunnel Sink when an existing Source, Transform, and Sink pipeline should be reused, or Spark Connector from a Spark job.

• Import data with Loader
• Import graph data with SeaTunnel Sink
• Read and write graph data with Spark Connector

2.3.1 - Import Graph Data with SeaTunnel Sink

SeaTunnel connects data sources such as databases and Kafka to HugeGraph. The connector has two parts: Source reads data and Sink writes data^[1][2], with SeaTunnel transform components available between them. To export or migrate data from HugeGraph, see the SeaTunnel Source export and migration guide.

Version requirement: This guide targets SeaTunnel 3.0+. All examples use the mappings configuration available in SeaTunnel 3.0+.

Click a diagram to view the original size.

1 Loader, Tools, and SeaTunnel

HugeGraph-Loader is suited to direct imports from common data sources. HugeGraph-Tools focuses on standalone graph management, backup, and export. SeaTunnel organizes a job as Source → Transform → Sink, so you can reuse existing connectors, transforms, and data pipelines.

Table legend

✅ Supported natively; ⚠️ conditional support or requires an extra component/external platform; ❌ not provided

SeaTunnel covers Loader’s graph-import and Tools’ export and migration scenarios in one expandable pipeline, and it also supports SQL-CDC and dozens of input and output types. Loader and Tools normally run on one machine, while SeaTunnel supports both standalone and distributed deployments and scales with data and task volume. Tools’ schedule-backup can create a crontab entry, but it does not provide unified workflow orchestration and resource management.

Existing Spark/Flink daily jobs

Both HugeGraph Source and Sink list SeaTunnel Engine (Zeta), Spark, and Flink as supported engines in SeaTunnel 3.0+. If you express the daily job as a SeaTunnel job and submit it to that engine, records can move directly from Source to Transform to Sink without an intermediate file. If you keep the existing Spark/Flink DAG, SeaTunnel does not automatically take over its in-memory DataFrame or stream. Adapt it into a SeaTunnel job or expose the data through a Source connector

Loader and Tools are focused, direct, and quick to start. Use Loader for a direct graph import; use Tools for backup, restore, export, or daily operations. If a SeaTunnel job already exists, adding HugeGraph to that pipeline is usually simpler. For higher import throughput, Loader’s bypass-server path and other import optimizations are a better fit; measured peaks of 1-2 million records/s require a specific backend, data set, and hardware configuration and are not a general performance guarantee. For new SeaTunnel jobs, use 3.0+ and mappings. Recheck the connector configuration when using another version.

2 Prepare the environment

2.1 Get SeaTunnel 3.0+

Use JDK 11 and set JAVA_HOME; the official deployment guide lists Java 8 and 11 as prerequisites. Choose a 3.0+ binary distribution from the official release page^[4] and verify its checksum or signature using the files linked there. The commands below use 3.0.0 as an example; set SEATUNNEL_VERSION to the release you downloaded.

1export SEATUNNEL_VERSION=3.0.0
2tar -xzf "apache-seatunnel-${SEATUNNEL_VERSION}-bin.tar.gz"
3cd "apache-seatunnel-${SEATUNNEL_VERSION}"

The binary distribution does not include connector plugins. In config/plugin_config, select the connectors needed by the examples:

1--seatunnel-connectors--
2connector-hugegraph
3connector-jdbc
4connector-kafka
5--end--

Install the matching released plugins using the upstream plugin installation instructions^[5]:

1sh bin/install-plugin.sh "${SEATUNNEL_VERSION}"

Run the remaining commands from this installation directory and keep the engine and connector plugins at the same version. This guide uses the bundled Zeta engine in local mode^[6][7]. Check that connectors/ contains HugeGraph, JDBC, and Kafka as needed^[11][12]. The JDBC examples also require the MySQL driver JAR in lib/, with driver class com.mysql.cj.jdbc.Driver.

2.2 Prepare HugeGraph and data sources

Start HugeGraph Server and create a graph for testing. The examples use the hugegraph graph in the DEFAULT graph space. Adjust these names to match the server configuration; graph space names are case-sensitive. If authentication is enabled, provide username and password in the HugeGraph Source and Sink configurations.

The following graph model is shared by the JDBC and Kafka examples. mappings creates missing PropertyKey, VertexLabel, and EdgeLabel definitions by default; existing schema definitions must be compatible.

The mysql, kafka, and hugegraph host names in the examples are placeholders. Replace them with addresses reachable from the SeaTunnel runtime. Inside a container, 127.0.0.1 points to that container; services on the same Docker network can use their service names. Set host to a host name or IP address, and set the port separately.

3 Import from a relational database (sql2graph)

Use two jobs for this import: write the person table as vertices first, then write the knows table as edges. Both edge endpoints will already exist when the edge job runs.

3.1 Import vertices

Prepare the sample data in the MySQL demo database and grant the configured account read access:

1CREATE TABLE person (
2  name VARCHAR(64) PRIMARY KEY,
3  age INT NOT NULL
4);
5INSERT INTO person VALUES ('marko', 29), ('vadas', 27);

Save the following as config/sql2graph-person.conf and replace the database user name and password:

 1env {
 2  job.mode = "BATCH"
 3}
 4
 5source {
 6  Jdbc {
 7    url = "jdbc:mysql://mysql:3306/demo?useSSL=false&serverTimezone=UTC"
 8    driver = "com.mysql.cj.jdbc.Driver"
 9    username = "seatunnel"
10    password = "change_me"
11    query = "SELECT name, age FROM person ORDER BY name"
12  }
13}
14
15sink {
16  HugeGraph {
17    host = "hugegraph"
18    port = 8080
19    graph_name = "hugegraph"
20    graph_space = "DEFAULT"
21    batch_failure_fallback = false
22    mappings = [
23      {
24        type = "VERTEX"
25        label = "person"
26        idStrategy = "PRIMARY_KEY"
27        idFields = ["name"]
28        properties = ["name", "age"]
29      }
30    ]
31  }
32}

1./bin/seatunnel.sh --config ./config/sql2graph-person.conf -m local

Check the result in Hubble or Gremlin. You should find marko and vadas with their ages:

1g.V().hasLabel('person').valueMap('name', 'age')

idFields = ["name"] uses the name to generate the primary key. Importing the same name again writes to the same vertex. properties lists the source fields to write.

3.2 Import edges

Prepare the relation table. Its two endpoint fields correspond to person.name from the vertex job:

1CREATE TABLE knows (
2  source_name VARCHAR(64) NOT NULL,
3  target_name VARCHAR(64) NOT NULL,
4  since INT NOT NULL
5);
6INSERT INTO knows VALUES ('marko', 'vadas', 2010);

 1env {
 2  job.mode = "BATCH"
 3}
 4
 5source {
 6  Jdbc {
 7    url = "jdbc:mysql://mysql:3306/demo?useSSL=false&serverTimezone=UTC"
 8    driver = "com.mysql.cj.jdbc.Driver"
 9    username = "seatunnel"
10    password = "change_me"
11    query = "SELECT source_name, target_name, since FROM knows ORDER BY source_name, target_name"
12  }
13}
14
15sink {
16  HugeGraph {
17    host = "hugegraph"
18    port = 8080
19    graph_name = "hugegraph"
20    graph_space = "DEFAULT"
21    batch_failure_fallback = false
22    check_vertex = true
23    mappings = [
24      {
25        type = "EDGE"
26        label = "knows"
27        sourceConfig = {
28          label = "person"
29          idFields = ["source_name"]
30        }
31        targetConfig = {
32          label = "person"
33          idFields = ["target_name"]
34        }
35        fieldMapping = {
36          source_name = "name"
37          target_name = "name"
38        }
39        properties = ["since"]
40      }
41    ]
42  }
43}

After the vertex job succeeds, run the edge job:

1./bin/seatunnel.sh --config ./config/sql2graph-knows.conf -m local

The following query should return a knows edge from marko to vadas with since set to 2010:

1g.V().has('person', 'name', 'marko').outE('knows').where(inV().has('name', 'vadas')).valueMap()

sourceConfig and targetConfig identify the endpoint fields. fieldMapping maps them to the vertex primary key name, and properties = ["since"] writes only the edge property. The example enables check_vertex = true and disables per-record fallback after a batch failure (batch_failure_fallback = false), so a missing endpoint or write failure causes the job to fail.

If the relation table has only numeric foreign keys while the graph uses names as primary keys, join the names in SQL before passing the records to the Sink. See MySQL CDC Source^[13] for MySQL CDC integration.

4 Import from Kafka (kafka2graph)

Kafka is useful for a continuous stream of events. Create the user-events topic and publish the following JSON message. Each message becomes one person vertex:

1{"name":"marko","age":29}

Save the following as config/kafka2graph.conf:

 1env {
 2  job.mode = "STREAMING"
 3  checkpoint.interval = 10000
 4  sink.flush.interval = 5000
 5}
 6
 7source {
 8  Kafka {
 9    bootstrap.servers = "kafka:9092"
10    topic = "user-events"
11    consumer.group = "hugegraph-import"
12    start_mode = "earliest"
13    format = "json"
14    schema = {
15      fields = {
16        name = "string"
17        age = "int"
18      }
19    }
20  }
21}
22
23sink {
24  HugeGraph {
25    host = "hugegraph"
26    port = 8080
27    graph_name = "hugegraph"
28    graph_space = "DEFAULT"
29    batch_failure_fallback = false
30    mappings = [
31      {
32        type = "VERTEX"
33        label = "person"
34        idStrategy = "PRIMARY_KEY"
35        idFields = ["name"]
36        properties = ["name", "age"]
37      }
38    ]
39  }
40}

1./bin/seatunnel.sh --config ./config/kafka2graph.conf -m local

Use the Gremlin query from section 3.1 to check the data. The streaming job keeps running. checkpoint.interval saves job state every 10 seconds, while sink.flush.interval asks Zeta to flush every 5 seconds so a small number of messages does not wait for a full batch.

HugeGraph Sink writes with at-least-once semantics, so recovery can replay records. PRIMARY_KEY sends the same name to the same vertex, but it does not make every update exactly-once. Scheduled flushing is provided by Zeta and does not apply to Spark or Flink engines.

5 Common configuration and troubleshooting

The following table applies to the SeaTunnel 3.0+ version used by this guide: