A graph database that supports more than 10 billion vertices & edges, high performance and scalability

---

Quick Navigation: Architecture • Quick Start • Module Map • Ecosystem • For Contributors • Community

---

What is Apache HugeGraph?

HugeGraph is a fast and highly-scalable graph database. Billions of vertices and edges can be easily stored into and queried from HugeGraph due to its excellent OLTP capabilities. HugeGraph is compliant with the Apache TinkerPop 3 framework allowing complicated graph queries to be achieved through the powerful Gremlin graph traversal language.

Features

• Schema Metadata Management: VertexLabel, EdgeLabel, PropertyKey, and IndexLabel
• Multi-type Indexes: Exact query, range query, and complex conditions combination query
• Plug-in Backend Store Framework: Mainly supports RocksDB/HStore + HBase; other backends available in legacy versions ≤ 1.5.0 (MySQL/PostgreSQL/Cassandra...)
• Big Data Integration: Seamless integration with Flink/Spark/HDFS
• Complete Graph Ecosystem: In/out-memory Graph Computing + Graph Visualization & Tools + Graph Learning & AI
• Dual Query Language Support: Gremlin (via Apache TinkerPop 3) and Cypher (OpenCypher)

Ecosystem

Complete HugeGraph ecosystem components:

1. hugegraph-toolchain - Graph tools suite

   • Loader - Data import tool
   • Dashboard - Web visualization platform
   • Tool - Command-line utilities
   • Client - Java/Python client SDK

2. hugegraph-computer - Integrated graph computing system

3. hugegraph-ai - Graph AI/LLM/Knowledge Graph integration

4. hugegraph-website - Documentation & website repository

Architecture

HugeGraph supports both standalone and distributed deployments:

                        ┌─────────────────────────────────────────────────────┐
                        │                    Client Layer                     │
                        │  Gremlin Console │ REST API │ Cypher │ SDK/Tools    │
                        └─────────────────────────┬───────────────────────────┘
                                                  │
                        ┌─────────────────────────▼───────────────────────────┐
                        │             HugeGraph Server (:8080)                │
                        │  ┌──────────┐  ┌──────────┐  ┌──────────────────┐   │
                        │  │ REST API │  │ Gremlin  │  │   Cypher Engine  │   │
                        │  │(Jersey 3)│  │ (TP 3.5) │  │   (OpenCypher)   │   │
                        │  └────┬─────┘  └────┬─────┘  └────────┬─────────┘   │
                        │       └─────────────┼─────────────────┘             │
                        │            ┌────────▼────────┐                      │
                        │            │  Graph Engine   │                      │
                        │            │(hugegraph-core) │                      │
                        │            └────────┬────────┘                      │
                        └─────────────────────┼───────────────────────────────┘
                                              │
             ┌────────────────────────────────┼────────────────────────────────┐
             │                                │                                │
┌────────────▼────────────┐   ┌───────────────▼───────────────┐   ┌───────────▼──────────┐
│    Standalone Mode      │   │      Distributed Mode         │   │   Legacy Backends    │
│  ┌───────────────────┐  │   │  ┌─────────────────────────┐  │   │      (≤v1.5)         │
│  │      RocksDB      │  │   │  │     HugeGraph-PD        │  │   │  MySQL │ PostgreSQL  │
│  │    (embedded)     │  │   │  │   (Raft, 3-5 nodes)     │  │   │  Cassandra           │
│  └───────────────────┘  │   │  │      :8620/:8686        │  │   │  HBase (≤v1.7)       │
│                         │   │  └────────────┬────────────┘  │   └──────────────────────┘
│  Use Case:              │   │               │               │
│  Development/Testing    │   │  ┌────────────▼────────────┐  │
│  Single Node            │   │  │    HugeGraph-Store      │  │
│                         │   │  │    (Raft + RocksDB)     │  │
│  Data Scale: < 1TB      │   │  │   (3+ nodes) :8520      │  │
└─────────────────────────┘   │  └─────────────────────────┘  │
                              │                               │
                              │  Use Case:                    │
                              │  Production/HA/Cluster        │
                              │                               │
                              │  Data Scale: < 1000 TB        │
                              └───────────────────────────────┘

Deployment Mode Comparison

Mode	Components	Use Case	Data Scale	High Availability
Standalone	Server + RocksDB	Development, Testing, Single Node	< 1TB	Basic
Distributed	Server + PD (3-5 nodes) + Store (3+ nodes)	Production, HA, Horizontal Scaling	< 1000 TB	Yes

Module Overview

Module	Description
hugegraph-server	Core graph engine with REST API, Gremlin/Cypher support, and pluggable backends (RocksDB default)
hugegraph-pd	Placement Driver for distributed mode - handles meta storage, partition management and cluster scheduling
hugegraph-store	Distributed storage with Raft consensus for high availability and horizontal scaling
hugegraph-commons	Shared utilities, RPC framework and common components

📊 Click to view detailed architecture diagram (Mermaid)

flowchart TB
    subgraph Clients["Client Layer"]
        GC[Gremlin Console]
        REST[REST Client]
        CYPHER[Cypher Client]
        SDK[SDK/Tools]
    end

    subgraph Server["HugeGraph Server :8080"]
        API[REST API<br/>Jersey 3]
        GS[Gremlin Server<br/>TinkerPop 3.5]
        CS[Cypher Engine<br/>OpenCypher]
        CORE[Graph Engine<br/>hugegraph-core]

        API --> CORE
        GS --> CORE
        CS --> CORE
    end

    subgraph Storage["Storage Layer"]
        subgraph Standalone["Standalone Mode"]
            ROCKS[(RocksDB<br/>Embedded)]
        end

        subgraph Distributed["Distributed Mode"]
            PD[HugeGraph-PD<br/>Raft Cluster<br/>:8620/:8686]
            STORE[HugeGraph-Store<br/>Raft + RocksDB<br/>:8520]
            PD <--> STORE
        end

        subgraph Legacy["Legacy Backends (≤v1.5)"]
            MYSQL[(MySQL)]
            PG[(PostgreSQL)]
            CASS[(Cassandra)]
            HBASE[(HBase, ≤v1.7)]
        end
    end

    Clients --> Server
    CORE --> ROCKS
    CORE --> PD
    CORE -.-> Legacy

    style Server fill:#e1f5ff
    style Distributed fill:#fff4e1
    style Standalone fill:#f0f0f0

Loading

Quick Start

5 Minutes Quick Start

# Start HugeGraph with Docker
docker run -itd --name=hugegraph -p 8080:8080 hugegraph/hugegraph:1.7.0

# Verify server is running
curl http://localhost:8080/apis/version

# Try a Gremlin query
curl -X POST http://localhost:8080/gremlin \
  -H "Content-Type: application/json" \
  -d '{"gremlin":"g.V().limit(5)"}'

Production Note: For production environments or public network exposure, you must enable the AuthSystem for security.

Prerequisites

• Java 11+ (required)
• Maven 3.5+ (for building from source)

Option 1: Docker (Fastest)

Docker is the quickest way to get started for testing or development:

# Basic usage
docker run -itd --name=hugegraph -p 8080:8080 hugegraph/hugegraph:1.7.0

# With sample graph preloaded
docker run -itd --name=hugegraph -e PRELOAD=true -p 8080:8080 hugegraph/hugegraph:1.7.0

# With authentication enabled
docker run -itd --name=hugegraph -e PASSWORD=your_password -p 8080:8080 hugegraph/hugegraph:1.7.0

For advanced Docker configurations, see:

• Docker Documentation
• Docker Compose Example
• Docker README

Note: Docker images are convenience releases, not official ASF distribution artifacts. See ASF Release Distribution Policy for details.

Version Tags: Use release tags (1.7.0, 1.x.0) for stable versions. Use latest for development features.

Option 2: Download Binary Package

Download pre-built packages from the Download Page:

# Download and extract
wget https://downloads.apache.org/incubator/hugegraph/{version}/apache-hugegraph-incubating-{version}.tar.gz
tar -xzf apache-hugegraph-incubating-{version}.tar.gz
cd apache-hugegraph-incubating-{version}

# Initialize backend storage
bin/init-store.sh

# Start server
bin/start-hugegraph.sh

# Check server status
bin/monitor-hugegraph.sh

For detailed instructions, see the Binary Installation Guide.

Option 3: Build from Source

Build from source for development or customization:

# Clone repository
git clone https://github.com/apache/hugegraph.git
cd hugegraph

# Build all modules (skip tests for faster build)
mvn clean package -DskipTests

# Extract built package
cd install-dist/target
tar -xzf hugegraph-{version}.tar.gz
cd hugegraph-{version}

# Initialize and start
bin/init-store.sh
bin/start-hugegraph.sh

For detailed build instructions, see BUILDING.md and Build from Source Guide.

Verify Installation

Once the server is running, verify the installation:

# Check server version
curl http://localhost:8080/apis/version

# Expected output:
# {
#   "version": "1.7.0",
#   "core": "1.7.0",
#   "gremlin": "3.5.1",
#   "api": "1.7.0"
# }

# Try Gremlin console (if installed locally)
bin/gremlin-console.sh

# In Gremlin console:
gremlin> :remote connect tinkerpop.server conf/remote.yaml
gremlin> :> g.V().limit(5)

For comprehensive documentation, visit the HugeGraph Documentation.

Module Map

Developer Navigation: Find the right module for your task

I want to...	Module	Key Path
Understand graph operations	hugegraph-core	StandardHugeGraph.java
Modify REST APIs	hugegraph-api	src/.../api/
Add storage backend	hugegraph-core	BackendStore.java
Develop Gremlin features	hugegraph-core	src/.../traversal/
Develop Cypher features	hugegraph-api	src/.../opencypher/
Work on distributed coordination	hugegraph-pd	hg-pd-core/
Work on distributed storage	hugegraph-store	hg-store-core/
Add backend implementations	hugegraph-server/hugegraph-{backend}	hugegraph-rocksdb/, hugegraph-hstore/
Understand configuration	hugegraph-dist	src/assembly/static/conf/
Run tests	hugegraph-test	Test suites with multiple profiles

For detailed architecture and development guidance, see AGENTS.md.

For Contributors

New to HugeGraph? Follow this path to get started:

1. Understand the Architecture

   • Read AGENTS.md for detailed module structure and development patterns
   • Review the Architecture Diagram above

2. Set Up Your Environment

   • Install Java 11+ and Maven 3.5+
   • Follow BUILDING.md for build instructions
   • Configure your IDE to use .editorconfig for code style and style/checkstyle.xml for Checkstyle rules

3. Find Your First Issue

   • Browse Good First Issues
   • Check Help Wanted Issues

4. Learn the Codebase

   • Use the Module Map to navigate
   • Try DeepWiki for AI-powered codebase understanding
   • Run tests to understand behavior: mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,memory
   • Try modifying a test and see what breaks

5. Code Standards

   • Line length: 100 characters
   • Indentation: 4 spaces
   • No star imports
   • Commit format: feat|fix|refactor(module): description

6. Submit Your Contribution

   • Read CONTRIBUTING.md for guidelines
   • Follow the Contribution Guidelines
   • Use GitHub Desktop to simplify the PR process

Contributing

Welcome to contribute to HugeGraph!

• How to Contribute: See CONTRIBUTING.md and Contribution Guidelines
• Code Style: Configure your IDE to use .editorconfig for code style and style/checkstyle.xml for Checkstyle rules
• PR Tool: GitHub Desktop is recommended for simpler workflow

Thank you to all the contributors who have helped make HugeGraph better!

License

HugeGraph is licensed under Apache 2.0 License.

Community

Get Help & Stay Connected

• GitHub Issues: Report bugs and request features (quick response)
• Mailing List: [email protected] (subscribe here)
• Slack: ASF HugeGraph Channel
• WeChat: Scan the QR code to follow Apache HugeGraph official account

Thanks

HugeGraph relies on the Apache TinkerPop framework. We are grateful to the TinkerPop community, Titan, and DataStax for their foundational work. Thanks to all contributors and organizations who have helped make HugeGraph possible.

You are welcome to contribute to HugeGraph, and we look forward to working with you to build an excellent open-source community.