blob: 914805066a7688043c700c589d116bee22aa3498 [file] [view]
# 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:
```bash
ROOT_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
cd "$ROOT_DIR"
```
---
## Quick Start Paths (Choose One)
<details>
<summary><b>Option 1: Standalone HugeGraph (using start-hugegraph.sh)</b></summary>
Prerequisite: build local artifact first.
mvn clean package -DskipTests
```
cd "$ROOT_DIR"
```
```bash
# 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
```
```bash
# 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"
```
```bash
# 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
```
</details>
<details>
<summary><b>Option 2: Docker HugeGraph (fully containerized)</b></summary>
```
cd "$ROOT_DIR"
```
```bash
# 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
```
```bash
# 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"
```
```bash
# 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
'
```
```bash
# 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
'
```
```bash
# 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"
```
</details>
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.
```bash
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:
```bash
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):
```bash
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:
```bash
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):
```bash
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):
```bash
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:
```bash
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:
```bash
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
```bash
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
```bash
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`