HugeGraph + HBase Backend

This guide covers running HugeGraph with HBase backend.

Deprecation notice: The HBase backend is deprecated and is planned for removal in HugeGraph 2.0. Existing deployments should plan a migration to a maintained backend.

All commands below run from the repository root (this project folder).

Use this once at the start of your terminal session:

ROOT_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
cd "$ROOT_DIR"

---

Quick Start Paths (Choose One)

Prerequisite: build local artifact first. mvn clean package -DskipTests

cd "$ROOT_DIR"

# 1) Start HBase
docker compose -p hg-hbase -f docker/hbase/docker-compose.hbase.yml down -v
docker compose -p hg-hbase -f docker/hbase/docker-compose.hbase.yml build --no-cache hbase
HBASE_MASTER_HOSTNAME=localhost HBASE_REGIONSERVER_HOSTNAME=localhost \
docker compose -p hg-hbase -f docker/hbase/docker-compose.hbase.yml up -d
until docker exec hg-hbase-test nc -z localhost 2181 >/dev/null 2>&1; do sleep 2; done
echo "HBase ZooKeeper is reachable on 2181"
# Optional troubleshooting stream:
# docker compose -p hg-hbase -f docker/hbase/docker-compose.hbase.yml logs -f hbase

# 2) Configure HugeGraph (standalone runtime)
SERVER_DIR="$(find . -maxdepth 4 -type d -path './hugegraph-server/apache-hugegraph-server-*' | head -n 1)"
[ -n "$SERVER_DIR" ] || { echo "Build artifact not found"; exit 1; }
CONF="$SERVER_DIR/conf/graphs/hugegraph.properties"

perl -pi -e 's/^backend=.*/backend=hbase/' "$CONF"
perl -pi -e 's/^serializer=.*/serializer=hbase/' "$CONF"
perl -pi -e 's/^#(hbase\.hosts=.*)/$1/' "$CONF"
perl -pi -e 's/^#(hbase\.port=.*)/$1/' "$CONF"
perl -pi -e 's/^#(hbase\.znode_parent=.*)/$1/' "$CONF"
perl -pi -e 's/^hbase\.hosts=.*/hbase.hosts=localhost/' "$CONF"
perl -pi -e 's/^hbase\.port=.*/hbase.port=2181/' "$CONF"
perl -pi -e 's|^hbase\.znode_parent=.*|hbase.znode_parent=/hbase|' "$CONF"

grep -E '^(backend|serializer|hbase\.)' "$CONF"

# 3) Init and start server
cd "$SERVER_DIR"
printf 'pa\npa\n' | ./bin/init-store.sh
./bin/start-hugegraph.sh

# 4) Verify backend logs mention hbase
cd "$ROOT_DIR"
grep -Eai 'hbase|rocksdb|hstore' "$SERVER_DIR"/logs/*.log | tail -n 30

cd "$ROOT_DIR"

# 1) Start HBase
docker compose -p hg-hbase -f docker/hbase/docker-compose.hbase.yml down -v
docker compose -p hg-hbase -f docker/hbase/docker-compose.hbase.yml build --no-cache hbase
HBASE_HOSTNAME=hbase docker compose -p hg-hbase -f docker/hbase/docker-compose.hbase.yml up -d
until docker exec hg-hbase-test nc -z localhost 2181 >/dev/null 2>&1; do sleep 2; done
echo "HBase ZooKeeper is reachable on 2181"
# Optional troubleshooting stream:
# docker compose -p hg-hbase -f docker/hbase/docker-compose.hbase.yml logs -f hbase

# 2) Build HugeGraph server image
docker build -f hugegraph-server/Dockerfile -t hugegraph/server:dev .

# 3) Resolve HBase network
HBASE_NETWORK="$(docker inspect -f '{{range $k,$v := .NetworkSettings.Networks}}{{println $k}}{{end}}' hg-hbase-test | head -n 1)"
echo "$HBASE_NETWORK"

# 4) One-shot init-store
docker rm -f hg-server-init >/dev/null 2>&1 || true
docker run --rm --name hg-server-init \
  --network "$HBASE_NETWORK" \
  hugegraph/server:dev \
  bash -lc '
    set -euo pipefail
    CONF=/hugegraph-server/conf/graphs/hugegraph.properties
    perl -pi -e "s/^backend=.*/backend=hbase/" "$CONF"
    perl -pi -e "s/^serializer=.*/serializer=hbase/" "$CONF"
    perl -pi -e "s/^#(hbase\.hosts=.*)/\$1/" "$CONF"
    perl -pi -e "s/^#(hbase\.port=.*)/\$1/" "$CONF"
    perl -pi -e "s/^#(hbase\.znode_parent=.*)/\$1/" "$CONF"
    perl -pi -e "s/^hbase\.hosts=.*/hbase.hosts=hbase/" "$CONF"
    perl -pi -e "s/^hbase\.port=.*/hbase.port=2181/" "$CONF"
    perl -pi -e "s|^hbase\.znode_parent=.*|hbase.znode_parent=/hbase|" "$CONF"
    printf "pa\npa\n" | ./bin/init-store.sh
  '

# 5) Start HugeGraph container
docker rm -f hg-server-dev-hbase >/dev/null 2>&1 || true
docker run -d --name hg-server-dev-hbase \
  --network "$HBASE_NETWORK" \
  -p 8080:8080 \
  -p 8182:8182 \
  hugegraph/server:dev \
  bash -lc '
    set -euo pipefail
    CONF=/hugegraph-server/conf/graphs/hugegraph.properties
    perl -pi -e "s/^backend=.*/backend=hbase/" "$CONF"
    perl -pi -e "s/^serializer=.*/serializer=hbase/" "$CONF"
    perl -pi -e "s/^#(hbase\.hosts=.*)/\$1/" "$CONF"
    perl -pi -e "s/^#(hbase\.port=.*)/\$1/" "$CONF"
    perl -pi -e "s/^#(hbase\.znode_parent=.*)/\$1/" "$CONF"
    perl -pi -e "s/^hbase\.hosts=.*/hbase.hosts=hbase/" "$CONF"
    perl -pi -e "s/^hbase\.port=.*/hbase.port=2181/" "$CONF"
    perl -pi -e "s|^hbase\.znode_parent=.*|hbase.znode_parent=/hbase|" "$CONF"
    ./bin/start-hugegraph.sh -t 120
    tail -f /hugegraph-server/logs/hugegraph-server.log
  '

# 6) Verify hbase backend
docker exec hg-server-dev-hbase bash -lc "grep -E '^(backend|serializer|hbase\.)' /hugegraph-server/conf/graphs/hugegraph.properties"
docker exec hg-server-dev-hbase bash -lc "grep -Ei 'hbase|rocksdb|hstore' /hugegraph-server/logs/*.log | tail -n 30"

After either path is up, run the shared tests below.

---

Common Testing Steps

Apache HugeGraph Persistent Runbook (REST Engine)

Prerequisites and Constants

• Base URL: http://localhost:8080
• Graph target name: hugegraph
• Storage backend: persistent (HBase/RocksDB/HStore)

---

Step 1: Purge Database (Fresh Restart)

Wipe any conflicting test records and data schema.

curl -X DELETE "http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/clear?confirm_message=I%27m+sure+to+delete+all+data"

Status 204 No Content confirms success.

---

Step 2: Provision Structural Schema

1. Register property keys:

curl -X POST -H "Content-Type: application/json" \
  -d '{"name": "name", "data_type": "TEXT", "cardinality": "SINGLE"}' \
  "http://localhost:8080/graphs/hugegraph/schema/propertykeys"

2. Register vertex label (PRIMARY_KEY):

curl -X POST -H "Content-Type: application/json" \
  -d '{"name": "person", "id_strategy": "PRIMARY_KEY", "properties": ["name"], "primary_keys": ["name"]}' \
  "http://localhost:8080/graphs/hugegraph/schema/vertexlabels"

3. Register edge label:

curl -X POST -H "Content-Type: application/json" \
  -d '{"name": "knows", "source_label": "person", "target_label": "person", "properties": []}' \
  "http://localhost:8080/graphs/hugegraph/schema/edgelabels"

---

Step 3: Populate Graph Elements

1. Batch write vertices (Alice and Bob):

curl -X POST -H "Content-Type: application/json" \
  -d '[{"label": "person", "properties": {"name": "Alice"}}, {"label": "person", "properties": {"name": "Bob"}}]' \
  "http://localhost:8080/graphs/hugegraph/graph/vertices/batch"

Response should include IDs similar to 1:Alice and 1:Bob.

2. Create directed edge (Alice knows Bob):

curl -X POST -H "Content-Type: application/json" \
  -d '{"label": "knows", "outV": "1:Alice", "inV": "1:Bob", "properties": {}}' \
  "http://localhost:8080/graphs/hugegraph/graph/edges"

---

Step 4: Synchronous Verification and Traversal

1. Verify target K-hop output:

curl -s "http://localhost:8080/graphs/hugegraph/traversers/kout?source=%221:Alice%22&direction=OUT&max_depth=1"

Expected output: {"vertices":["1:Bob"]}

2. Verify relation path structure:

curl -s "http://localhost:8080/graphs/hugegraph/traversers/rays?source=%221:Alice%22&direction=OUT&label=knows&max_depth=1"

Expected output contains: rays":[{"objects":["1:Alice","1:Bob"]}]

---

Troubleshooting Cheat Sheet

• URI syntax error: do not append literal " inside bare URLs. Use URL-encoded values (%22).
• Property missing errors: prefer native /traversers/* APIs for synchronous reads.

---

Cleanup

Run cleanup only after testing is complete.

Standalone HugeGraph + Docker HBase

cd "$SERVER_DIR" && ./bin/stop-hugegraph.sh
cd "$ROOT_DIR"
docker compose -p hg-hbase -f docker/hbase/docker-compose.hbase.yml down -v

Docker HugeGraph + Docker HBase

docker rm -f hg-server-init >/dev/null 2>&1 || true
docker rm -f hg-server-dev-hbase
docker compose -p hg-hbase -f docker/hbase/docker-compose.hbase.yml down -v

---

Troubleshooting

Symptom	Fix
UnknownHostException: hbase:16000	HugeGraph container is not on same Docker network as HBase. Verify HBASE_NETWORK and --network.
RocksDB logs in server output	backend=rocksdb still active; re-run backend config and restart.
TableNotFoundException on API calls	Tables not initialized; re-run init-store.sh from selected path.
Port 8182 already in use	lsof -i :8182 then kill <PID>.
HBase container not starting	Check lsof -i :2181; increase Docker memory to >= 4 GB.

---

Verification Checklist

• [ ] backend=hbase in hugegraph.properties
• [ ] Server logs show HBase client messages (not RocksDB/HStore)
• [ ] HBase tables exist in default_hugegraph:*
• [ ] REST runbook queries return expected graph data
• [ ] Data survives server restart

---

References

• HBase official docs: https://hbase.apache.org/
• HugeGraph HBase backend: hugegraph-server/hugegraph-hbase/
• HBase Docker Compose: docker/hbase/docker-compose.hbase.yml
• HBase Docker config: docker/hbase/hbase-site.xml