This page introduces the Apache HugeGraph repository: its purpose, capabilities, two deployment modes, and a tour of its primary components. For a deeper look at any component, refer to the following child pages: architecture internals (1.1), module dependency details (1.2), the server subsystem (2), the PD coordinator (3), the distributed store (4), and shared libraries (5).
Apache HugeGraph is an OLTP graph database designed to store and query graphs at scale (10+ billion vertices and edges). It is fully compliant with Apache TinkerPop 3 and supports both Gremlin and Cypher (OpenCypher) query languages over a REST API.
The current release is 1.7.0, requiring Java 11+ and Maven 3.5+ to build. The project is licensed under Apache 2.0.
Core capabilities at a glance:
| Capability | Details |
|---|---|
| Query languages | Gremlin (TinkerPop 3.5.1), OpenCypher |
| Schema management | VertexLabel, EdgeLabel, PropertyKey, IndexLabel |
| Index types | Exact, range, and compound condition queries |
| Storage backends | RocksDB (default), HStore, HBase; legacy: MySQL, PostgreSQL, Cassandra, ScyllaDB |
| Deployment modes | Standalone (single node) and Distributed (Raft-based cluster) |
| Data scale | Standalone: < 1 TB · Distributed: < 1,000 TB |
| Big data integration | Apache Flink, Spark, HDFS |
Sources: README.md26-37 pom.xml28-31 pom.xml88-98
HugeGraph supports two distinct deployment topologies.
Deployment Mode Comparison
| Mode | Required Components | Typical Use Case | Data Scale | HA |
|---|---|---|---|---|
| Standalone | hugegraph-server + RocksDB (embedded) | Development, testing, single node | < 1 TB | No |
| Distributed | hugegraph-server (3+) + hugegraph-pd (3–5) + hugegraph-store (3+) | Production, horizontal scaling | < 1,000 TB | Yes |
In standalone mode, the server embeds RocksDB directly. No external services are needed. The server listens on port 8080 by default.
In distributed mode:
hugegraph-pd runs as a 3–5 node Raft cluster (REST: 8620, gRPC: 8686, Raft: 8610)hugegraph-store runs as a 3+ node Raft cluster (gRPC: 8520)hugegraph-server instances coordinate through PD and Store over gRPCDeployment topology (code-level components)
Sources: README.md57-106 hugegraph-pd/AGENTS.md196-205 hugegraph-store/AGENTS.md51-57
The repository is a Maven multi-module project with a root pom.xml at pom.xml101-109 defining seven top-level modules.
Top-level modules
Sources: pom.xml101-109 AGENTS.md19-54 hugegraph-server/AGENTS.md80-98 hugegraph-pd/AGENTS.md24-53 hugegraph-store/AGENTS.md19-49
The primary user-facing component. It exposes a JAX-RS REST API (Jersey 3 / Grizzly) on port 8080, an embedded Gremlin server, and a Cypher engine.
Key classes:
| Class | Module | Role |
|---|---|---|
RestServer | hugegraph-api | Starts and configures the Jersey/Grizzly HTTP server |
GremlinAPI | hugegraph-api | Handles /gremlin endpoint (POST queries) |
CypherAPI | hugegraph-api | Handles /cypher endpoint (OpenCypher translation) |
GraphsAPI | hugegraph-api | CRUD operations for graph instances |
SchemaAPI | hugegraph-api | Manages vertex/edge labels, property keys, index labels |
StandardHugeGraph | hugegraph-core | Central graph implementation; delegates to BackendStore |
GraphManager | hugegraph-api | Manages graph instance lifecycle, loads config via MetaManager |
HugeGraphAuthProxy | hugegraph-core | Permission-checking wrapper around StandardHugeGraph |
BackendStore | hugegraph-core | Interface implemented by all storage backends |
The backend is selected at runtime via the backend property in hugegraph.properties. Backend JARs (hugegraph-rocksdb, hugegraph-hstore, etc.) are loaded through Java ServiceLoader.
Sources: hugegraph-server/AGENTS.md1-11 hugegraph-server/AGENTS.md101-135 AGENTS.md31-44
The Placement Driver — a metadata coordination service required only in distributed deployments. It runs as a Raft cluster (typically 3 or 5 nodes) and is responsible for:
PartitionService)StoreNodeService)MetadataRocksDBStore)DiscoveryService)The entry point is HgPdApplication (Spring Boot application in hg-pd-service). All external communication uses gRPC; proto definitions live in hg-pd-grpc/src/main/proto/ (files: pdpb.proto, metapb.proto, discovery.proto, etc.).
Sources: hugegraph-pd/AGENTS.md1-53 AGENTS.md48-53
The distributed storage layer. Each node persists graph data in RocksDB and participates in Raft consensus groups for replication. It receives data plane traffic from hugegraph-server (via the hugegraph-hstore backend module and hg-store-client) and receives partition assignments from hugegraph-pd.
Key sub-modules: hg-store-core, hg-store-node (Raft integration), hg-store-rocksdb, hg-store-client.
Sources: hugegraph-store/AGENTS.md1-57 hugegraph-store/AGENTS.md168-230
A shared library consumed by all other modules. Provides:
HugeConfig — loads and validates .properties / .yaml config files using typed ConfigOption definitionsLockManager, KeyLock, RowLock — concurrency primitivesEventHub — async event notificationRpcServer / RpcClientProvider — Sofa-RPC abstraction layerSources: hugegraph-commons/AGENTS.md21-68
A foundational, stateless data-structure library shared by hugegraph-pd, hugegraph-store, and hugegraph-server. It was extracted from hugegraph-core to break circular dependencies. It must be built before PD and Store.
Provides: schema element definitions (VertexLabel, EdgeLabel, PropertyKey, IndexLabel), type system (HugeType enum), ID management (IdGenerator, EdgeId), binary serialization (BytesBuffer, BinaryElementSerializer), and query abstractions (ConditionQuery, IdQuery).
Sources: hugegraph-struct/README.md1-52 hugegraph-struct/AGENTS.md1-30
install-dist packages the final distribution tarball (hugegraph-<version>.tar.gz) combining all server, PD, and store artifacts, along with LICENSE, NOTICE, and startup scripts.
hugegraph-cluster-test contains integration tests that exercise the full three-tier distributed stack (server + PD + store). These tests are run by the cluster-test-ci.yml GitHub Actions workflow.
Sources: AGENTS.md25-27 hugegraph-store/AGENTS.md246-249
HugeGraph is the OLTP core of a broader ecosystem. The following external projects integrate with it over the REST API and/or Gremlin:
HugeGraph Ecosystem
Sources: README.md40-53 AGENTS.md56-60
The fastest way to run HugeGraph locally is via Docker:
To build from source (requires Java 11+, Maven 3.5+):
For build system details, see 6. For distributed deployment configuration, see 1.1.
Sources: README.md171-268 BUILDING.md1-10
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.
