License Build Status Build Status Build Status Build Status Maven Central Ask DeepWiki

A comprehensive suite of client SDKs, data tools, and management utilities for Apache HugeGraph graph database. Build applications, load data, and manage graphs with production-ready tools.

Quick Navigation: Architecture | Quick Start | Modules | Build | Docker | Related Projects

HugeGraph Ecosystem:

1. hugegraph - Core graph database (pd / store / server / commons )
2. hugegraph-computer - Distributed graph computing system
3. hugegraph-ai - Graph AI/LLM/Knowledge Graph integration
4. hugegraph-website - Documentation and website

graph TB
 subgraph server ["HugeGraph Server"]
 SERVER[("Graph Database")]
 end
 subgraph distributed ["Distributed Mode (Optional)"]
 PD["hugegraph-pd<br/>(Placement Driver)"]
 STORE["hugegraph-store<br/>(Storage Nodes)"]
 end
 subgraph clients ["Client SDKs"]
 CLIENT["hugegraph-client<br/>(Java)"]
 end
 subgraph data ["Data Tools"]
 LOADER["hugegraph-loader<br/>(Batch Import)"]
 SPARK["hugegraph-spark-connector<br/>(Spark I/O)"]
 end
 subgraph mgmt ["Management Tools"]
 HUBBLE["hugegraph-hubble<br/>(Web UI)"]
 TOOLS["hugegraph-tools<br/>(CLI)"]
 end
 SERVER <-->|REST API| CLIENT
 PD -.->|coordinates| STORE
 SERVER -.->|distributed backend| PD
 CLIENT --> LOADER
 CLIENT --> HUBBLE
 CLIENT --> TOOLS
 CLIENT --> SPARK
 HUBBLE -.->|WIP: pd-client| PD
 LOADER -.->|Sources| SRC["CSV | JSON | HDFS<br/>MySQL | Kafka"]
 SPARK -.->|I/O| SPK["Spark DataFrames"]
 style distributed stroke-dasharray: 5 5

 ┌─────────────────────────┐
 │ HugeGraph Server │
 │ (Graph Database) │
 └───────────┬─────────────┘
 │ REST API
 ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┼ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐
 Distributed (Optional)│
 │ ┌───────────┐ │ ┌───────────┐ │
 │hugegraph- │◄──────┴──────►│hugegraph- │
 │ │ pd │ │ store │ │
 └───────────┘ └───────────┘
 └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘
 │
 ┌─────────────────────┼─────────────────────┐
 │ │ │
 ▼ ▼ ▼
 ┌────────────────┐ ┌────────────────┐ ┌────────────────┐
 │ hugegraph- │ │ Other Client │ │ Other REST │
 │ client (Java) │ │ SDKs (Go/Py) │ │ Clients │
 └───────┬────────┘ └────────────────┘ └────────────────┘
 │ depends on
 ┌───────┼───────────┬───────────────────┐
 │ │ │ │
 ▼ ▼ ▼ ▼
┌────────┐ ┌────────┐ ┌──────────┐ ┌───────────────────┐
│ loader │ │ hubble │ │ tools │ │ spark-connector │
│ (ETL) │ │ (Web) │ │ (CLI) │ │ (Spark I/O) │
└────────┘ └────────┘ └──────────┘ └───────────────────┘

# Hubble Web UI (port 8088)
docker run -d -p 8088:8088 --name hubble hugegraph/hugegraph-hubble
# Loader (batch data import)
docker run --rm hugegraph/hugegraph-loader ./bin/hugegraph-loader.sh -f example.json

Purpose: Official Java SDK for HugeGraph Server

Key Features:

• Schema management (PropertyKey, VertexLabel, EdgeLabel, IndexLabel)
• Graph operations (CRUD vertices/edges)
• Gremlin query execution
• Built-in traversers (shortest path, k-neighbor, k-out, paths, etc.)
• Multi-graph and authentication support

Entry Point: org.apache.hugegraph.driver.HugeClient

Quick Example:

HugeClient client = HugeClient.builder("http://localhost:8080", "hugegraph").build();
// Schema management
client.schema().propertyKey("name").asText().ifNotExist().create();
client.schema().vertexLabel("person")
 .properties("name")
 .ifNotExist()
 .create();
// Graph operations
Vertex vertex = client.graph().addVertex(T.label, "person", "name", "Alice");

📖 Documentation | 📁 Source

import "github.com/apache/hugegraph-toolchain/hugegraph-client-go"
client := hugegraph.NewClient("http://localhost:8080", "hugegraph")
// Schema and graph operations

Looking for other languages? See hugegraph-python-client in the hugegraph-ai repository.

Purpose: Batch data import tool from multiple data sources

Key Features:

• Sources: CSV, JSON, HDFS, MySQL, Kafka, existing HugeGraph
• JSON-based mapping configuration
• Parallel loading with configurable threads
• Error handling and retry mechanisms
• Progress tracking and logging

Entry Point: bin/hugegraph-loader.sh

Quick Example:

# Load data from CSV
./bin/hugegraph-loader.sh -f mapping.json -g hugegraph
# Example mapping.json structure
{
 "vertices": [
 {
 "label": "person",
 "input": { "type": "file", "path": "persons.csv" },
 "mapping": { "name": "name", "age": "age" }
 }
 ]
}

📖 Documentation | 📁 Source

Purpose: Web-based graph management and visualization platform

Key Features:

• Schema management with visual editor
• Data loading interface
• Graph visualization and exploration
• Gremlin query console
• Multi-graph workspace management
• User authentication and authorization

Technology Stack: Spring Boot + React + TypeScript + MobX + Ant Design

Entry Point: bin/start-hubble.sh (default port: 8088)

Quick Start:

cd hugegraph-hubble/apache-hugegraph-hubble-*/bin
./start-hubble.sh # Background mode
./start-hubble.sh -f # Foreground mode
./stop-hubble.sh # Stop server

📖 Documentation | 📁 Source

Purpose: Command-line utilities for graph operations

Key Features:

• Backup and restore graphs
• Graph migration
• Graph cloning
• Metadata management
• Batch operations

Entry Point: bin/hugegraph CLI commands

Quick Example:

# Backup graph
bin/hugegraph backup -t all -d ./backup
# Restore graph
bin/hugegraph restore -t all -d ./backup

📁 Source

Purpose: Spark integration for reading and writing HugeGraph data

Key Features:

• Read HugeGraph vertices/edges as Spark DataFrames
• Write DataFrames to HugeGraph
• Spark SQL support
• Distributed graph processing

Entry Point: Scala API with Spark DataSource v2

Quick Example:

// Read vertices as DataFrame
val vertices = spark.read
 .format("hugegraph")
 .option("host", "localhost:8080")
 .option("graph", "hugegraph")
 .option("type", "vertex")
 .load()
// Write DataFrame to HugeGraph
df.write
 .format("hugegraph")
 .option("host", "localhost:8080")
 .option("graph", "hugegraph")
 .save()

📁 Source

<!-- Note: Use the latest release version in Maven Central -->
<dependency>
 <groupId>org.apache.hugegraph</groupId>
 <artifactId>hugegraph-client</artifactId>
 <version>1.7.0</version>
</dependency>
<dependency>
 <groupId>org.apache.hugegraph</groupId>
 <artifactId>hugegraph-loader</artifactId>
 <version>1.7.0</version>
</dependency>

Check Maven Central for the latest versions.

mvn clean install -DskipTests -Dmaven.javadoc.skip=true -ntp

Checkstyle is enforced via tools/checkstyle.xml:

• Max line length: 100 characters
• 4-space indentation (no tabs)
• No star imports
• No System.out.println

Run checkstyle:

mvn checkstyle:check

Official Docker images are available on Docker Hub:

Examples:

# Hubble
docker run -d -p 8088:8088 --name hubble hugegraph/hugegraph-hubble
# Loader (mount config and data)
docker run --rm \
 -v /path/to/config:/config \
 -v /path/to/data:/data \
 hugegraph/hugegraph-loader \
 ./bin/hugegraph-loader.sh -f /config/mapping.json

Build images locally:

# Loader
cd hugegraph-loader && docker build -t hugegraph/hugegraph-loader:latest .
# Hubble
cd hugegraph-hubble && docker build -t hugegraph/hugegraph-hubble:latest .

• HugeGraph Toolchain Overview
• hugegraph-client Guide
• hugegraph-loader Guide
• hugegraph-hubble Guide
• API Reference

Welcome to contribute to HugeGraph! Please see How to Contribute for more information.

Note: It's recommended to use GitHub Desktop to simplify the PR and commit process.

Thank you to all the people who already contributed to HugeGraph!

contributors graph

• GitHub Issues - Report bugs and request features
• Email: dev@hugegraph.apache.org (subscriber only)
• Slack: ASF Channel
• WeChat: Apache HugeGraph (scan QR code below)

WeChat QR code

hugegraph-toolchain is licensed under Apache 2.0 License.