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

Module Overview

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

Quick Start

5 Minutes Quick Start

# Start HugeGraph (standalone mode)
docker run -itd --name=hugegraph -p 8080:8080 hugegraph/hugegraph:1.7.0

# Verify server is running
curl http://localhost:8080/versions

# 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 Examples
• Docker README
• Server Docker README

Docker Desktop (Mac/Windows): The 3-node distributed cluster (docker/docker-compose-3pd-3store-3server.yml) uses Docker bridge networking and works on all platforms including Docker Desktop. Allocate at least 12 GB memory to Docker Desktop.

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

Version Tags: Use release tags (e.g., 1.7.0) for stable deployments. The latest tag should only be used for testing or development.

# Download and extract
# For historical 1.7.0 and earlier releases, use the archive URL and
# set PACKAGE=apache-hugegraph-incubating-{version} instead.
BASE_URL="https://downloads.apache.org/hugegraph/{version}"
PACKAGE="apache-hugegraph-{version}"
# Historical alternative:
# BASE_URL="https://archive.apache.org/dist/incubator/hugegraph/{version}"
# PACKAGE="apache-hugegraph-incubating-{version}"

wget ${BASE_URL}/${PACKAGE}.tar.gz
tar -xzf ${PACKAGE}.tar.gz
cd ${PACKAGE}

# Initialize backend storage
bin/init-store.sh

# Start server
bin/start-hugegraph.sh

# Check server status
bin/monitor-hugegraph.sh

# 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

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

# Expected output:
# {
#   "versions": {
#     "version": "v1",
#     "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)

Module Map

Developer Navigation: Find the right module for your task

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

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: dev@hugegraph.apache.org (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.