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: RocksDB powers standalone deployments and HStore powers distributed clusters. See the backend evolution guide for compatibility details.
• 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.8.1)│  │   (OpenCypher)   │   │
                        │  └────┬─────┘  └────┬─────┘  └────────┬─────────┘   │
                        │       └─────────────┼─────────────────┘             │
                        │            ┌────────▼────────┐                      │
                        │            │  Graph Engine   │                      │
                        │            │(hugegraph-core) │                      │
                        │            └────────┬────────┘                      │
                        └─────────────────────┼───────────────────────────────┘
                                              │
                            ┌─────────────────┴─────────────────┐
                            │                                   │
             ┌──────────────▼──────────────┐     ┌──────────────▼──────────────┐
             │        Standalone Mode      │     │       Distributed Mode      │
             │  ┌───────────────────────┐  │     │  ┌───────────────────────┐  │
             │  │        RocksDB        │  │     │  │     HugeGraph-PD      │  │
             │  │      (embedded)       │  │     │  │   (Raft, 3-5 nodes)   │  │
             │  └───────────────────────┘  │     │  │      :8620/:8686      │  │
             │                             │     │  └───────────┬───────────┘  │
             │  Use Case:                  │     │              │              │
             │  Development/Testing        │     │  ┌───────────▼───────────┐  │
             │  Single Node                │     │  │         HStore        │  │
             │                             │     │  │    (Raft, 3+ nodes)   │  │
             │  Data Scale: < 1TB          │     │  │         :8520         │  │
             └─────────────────────────────┘     │  └───────────────────────┘  │
                                                 │                             │
                                                 │  Use Case:                  │
                                                 │  Production/HA/Cluster      │
                                                 │                             │
                                                 │  Data Scale: < 1000 TB      │
                                                 └─────────────────────────────┘

See the backend evolution guide for lifecycle and historical compatibility guidance.

To use ToplingDB with the RocksDB backend, follow the three-step switching guide.

Deployment Mode Comparison

Module Overview

See the 1.8.0 shared-foundation migration guide for Java API changes, module ownership and coordinated upgrade requirements.

flowchart TB
    CLIENTS["Client Layer<br/>Gremlin Console · REST Client · Cypher Client · SDK/Tools"]

    subgraph Server["HugeGraph Server :8080"]
        API[REST API<br/>Jersey 3]
        GS[Gremlin Server<br/>TinkerPop 3.8.1]
        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_HSTORE[PD + HStore<br/>Raft Cluster]
        end
    end

    CLIENTS --> Server
    CORE --> ROCKS
    CORE --> PD_HSTORE

    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 17 (required and currently the only supported Java release)
• Maven 3.6.3+ (for building from source)

The launch scripts reject Java versions older than 17. That minimum-version check does not qualify later Java releases; use Java 17 unless another release is explicitly listed as supported.

Read the Server runtime guide for client configuration and query compatibility checks.

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.

Option 2: Kubernetes with Helm

The HStore Helm chart deploys HugeGraph PD, Store, and Server as a distributed Kubernetes cluster. See the chart documentation for single-node and highly available presets, configuration, and upgrade guidance.

# 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
tar -xzf target/apache-hugegraph-{version}.tar.gz
cd apache-hugegraph-{version}/apache-hugegraph-server-{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.8.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 repository constraints and module 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: [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.