Skip to content

Version 1.7 of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

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.

2 Prerequisites

2.1 Requirements

  • Operating System: Linux or macOS (Windows has not been fully tested)
  • Java version: ≥ 11
  • 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

Download the latest version of HugeGraph-Store from the Apache HugeGraph official download page:

1# 1.7.0 is a historical release from the incubation period, so its file and directory names still include "incubating"
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

3.3 Docker Deployment

The HugeGraph-Store Docker image is available on Docker Hub as hugegraph/store.

Note: The following steps assume you have already cloned or pulled the HugeGraph main repository locally, or at least have its docker/ directory available.

Use the compose file to deploy the complete 3-node cluster (PD + Store + Server):

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-3pd-3store-3server.yml up -d

To run a single Store node via docker run:

 1docker run -d \
 2  -p 8520:8520 \
 3  -p 8500:8500 \
 4  -p 8510:8510 \
 5  -e HG_STORE_PD_ADDRESS=<pd-ip>:8686 \
 6  -e HG_STORE_GRPC_HOST=<your-ip> \
 7  -e HG_STORE_RAFT_ADDRESS=<your-ip>:8510 \
 8  -v /path/to/storage:/hugegraph-store/storage \
 9  --name hugegraph-store \
10  hugegraph/store:1.7.0

Environment variable reference:

VariableRequiredDefaultDescription
HG_STORE_PD_ADDRESSYes—PD gRPC addresses (e.g. pd0:8686,pd1:8686,pd2:8686)
HG_STORE_GRPC_HOSTYes—This node’s hostname/IP for gRPC (e.g. store0)
HG_STORE_RAFT_ADDRESSYes—This node’s Raft address (e.g. store0:8510)
HG_STORE_GRPC_PORTNo8500gRPC server port
HG_STORE_REST_PORTNo8520REST API port
HG_STORE_DATA_PATHNo/hugegraph-store/storageData storage path

Note: In Docker bridge networking, use container hostnames (e.g. store0) for HG_STORE_GRPC_HOST instead of IP addresses.

Deprecated aliases: PD_ADDRESS, GRPC_HOST, RAFT_ADDRESS still work but log a deprecation warning. Use the HG_STORE_* names for new deployments.

4 Configuration

The main configuration file for Store is conf/application.yml. Here are the key configuration items:

 1pdserver:
 2  # PD service address, multiple PD addresses are separated by commas (configure PD's gRPC port)
 3  address: 127.0.0.1:8686
 4
 5grpc:
 6  # gRPC service address
 7  host: 127.0.0.1
 8  port: 8500
 9  netty-server:
10    max-inbound-message-size: 1000MB
11
12raft:
13  # raft cache queue size
14  disruptorBufferSize: 1024
15  address: 127.0.0.1:8510
16  max-log-file-size: 600000000000
17  # Snapshot generation time interval, in seconds
18  snapshotInterval: 1800
19
20server:
21  # REST service address
22  port: 8520
23
24app:
25  # Storage path, supports multiple paths separated by commas
26  data-path: ./storage
27  #raft-path: ./storage
28
29spring:
30  application:
31    name: store-node-grpc-server
32  profiles:
33    active: default
34    include: pd
35
36logging:
37  config: 'file:./conf/log4j2.xml'
38  level:
39    root: info

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

  1. grpc.port (RPC port) for each node
  2. raft.address (Raft protocol port) for each node
  3. server.port (REST port) for each node
  4. app.data-path (data storage path) for each node

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 startup script supports a -d flag to control 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/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.

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

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

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
 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
10HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686
11HG_STORE_GRPC_HOST: store1
12HG_STORE_RAFT_ADDRESS: store1:8510
13
14# store2
15HG_STORE_PD_ADDRESS: pd0:8686,pd1:8686,pd2:8686
16HG_STORE_GRPC_HOST: store2
17HG_STORE_RAFT_ADDRESS: store2:8510

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

If it returns {"status":"UP"}, it indicates that the Store service has been successfully started.

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

1curl http://localhost:8620/v1/stores

If Store is configured successfully, the response should include status information for the current node, and state: "Up" means the node is running normally.

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}
Last modified 2026-09-04 · docs: sync 1.7 documentation (4211f768b)