hugegraph-toolchain

What is HugeGraph Toolchain?

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.

Related Projects

HugeGraph Ecosystem:

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

Architecture Overview

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

ASCII diagram (for terminals/editors)

 ┌─────────────────────────┐
│ 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) │
└────────┘ └────────┘ └──────────┘ └───────────────────┘

Quick Start

Prerequisites

Requirement	Version	Notes
JDK	11+	LTS recommended
Maven	3.6+	For building from source
HugeGraph Server	1.5.0+	Required for client/loader

Choose Your Path

I want to...	Use This	Get Started
Visualize graphs via Web UI	Hubble	Docker: `docker run -p 8088:8088 hugegraph/hugegraph-hubble`
Load CSV/JSON data into graph	Loader	CLI with JSON mapping config (docs)
Build a Java app with HugeGraph	Client	Maven dependency (example)
Backup/restore graphs	Tools	CLI commands (docs)
Process graphs with Spark	Spark Connector	DataFrame API (module)

Docker Quick Start

# 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

Module Overview

Before committing a new source or test file, run the same license-header check used by CI (license-eye from apache/skywalking-eyes is required):

./tools/check-license-header.sh

Do not use shortened Apache headers: the complete header configured in .licenserc.yaml is required.

hugegraph-client

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:

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

📖 Documentation | 📁 Source

Other Client SDKs

hugegraph-client-go (Go SDK - WIP)

Purpose: Official Go SDK for HugeGraph Server

Key Features:

RESTful API client for HugeGraph
Schema and graph operations
Gremlin query support
Idiomatic Go interface

Entry Point: github.com/apache/hugegraph-toolchain/hugegraph-client-go

Quick Example:

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

📁 Source

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

hugegraph-loader

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

hugegraph-hubble

Purpose: Web-based graph management and visualization platform

Key Features:

Multi-graph workspace & connection management
Interactive schema management with graphical editor
Comprehensive data loading dashboard
Dynamic graph visualization with path and topology canvas
Built-in Gremlin query console & algorithm explorer
Fine-grained user authentication & multi-language localization (i18n)

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

hugegraph-tools

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

hugegraph-spark-connector

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 DataFramevalvertices= 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

Maven Dependencies

<!-- 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.

Build & Development

Full Build

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

Module-Specific Builds

Module	Build Command
Client	`mvn -e compile -pl hugegraph-client -Dmaven.javadoc.skip=true -ntp`
Loader	`mvn install -pl hugegraph-client,hugegraph-loader -am -DskipTests -ntp`
Hubble	`mvn install -pl hugegraph-client,hugegraph-loader -am -DskipTests -ntp && cd hugegraph-hubble && mvn package -DskipTests -ntp`
Tools	`mvn install -pl hugegraph-client,hugegraph-tools -am -DskipTests -ntp`
Spark	`mvn install -pl hugegraph-client,hugegraph-spark-connector -am -DskipTests -ntp`
Go Client	`cd hugegraph-client-go && make all`

Running Tests

Module	Test Type	Command
Client	Unit (no server)	`mvn test -pl hugegraph-client -Dtest=UnitTestSuite`
Client	API (server needed)	`mvn test -pl hugegraph-client -Dtest=ApiTestSuite`
Client	Functional	`mvn test -pl hugegraph-client -Dtest=FuncTestSuite`
Loader	Unit	`mvn test -pl hugegraph-loader -P unit`
Loader	File sources	`mvn test -pl hugegraph-loader -P file`
Loader	HDFS	`mvn test -pl hugegraph-loader -P hdfs`
Loader	JDBC	`mvn test -pl hugegraph-loader -P jdbc`
Loader	Kafka	`mvn test -pl hugegraph-loader -P kafka`
Hubble	Unit	`mvn test -P unit-test -pl hugegraph-hubble/hubble-be`
Tools	Functional	`mvn test -pl hugegraph-tools -Dtest=FuncTestSuite`

Code Style

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

Docker

Official Docker images are available on Docker Hub:

Image	Purpose	Port
`hugegraph/hugegraph-hubble`	Web UI	8088
`hugegraph/hugegraph-loader`	Data loader	-

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
docker build -f hugegraph-loader/Dockerfile \
-t hugegraph/hugegraph-loader:latest .# Hubble
docker build -f hugegraph-hubble/Dockerfile \
-t hugegraph/hugegraph-hubble:latest .

Multi-platform builds use BuildKit's automatic platform arguments. The Maven and Node build stages run on $BUILDPLATFORM, while the final JRE stage uses $TARGETPLATFORM. Java bytecode and frontend assets are architecture-neutral, so they are built once without QEMU. Target-stage package installation still runs for each architecture.

This optimization applies only to architecture-independent build outputs. A component that compiles native code must use a target-platform build stage or separate platform stages. Loader and Hubble packaging is validated on arm64; native dependencies must still be audited. Loader includes arm64 variants for Snappy, LZ4, Commons Crypto, and gRPC tcnative. Some optional legacy HBase and Jansi natives remain x86-only, so their fallback paths require target-runtime validation when those optional features are used.

Documentation

Contributing

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!

Community & Contact

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

License

hugegraph-toolchain is licensed under Apache 2.0 License.

Name		Name	Last commit message	Last commit date
Latest commit History 817 Commits
.codex-task		.codex-task
.github		.github
.idea		.idea
.serena		.serena
assembly		assembly
hugegraph-client-go		hugegraph-client-go
hugegraph-client		hugegraph-client
hugegraph-dist		hugegraph-dist
hugegraph-hubble		hugegraph-hubble
hugegraph-loader		hugegraph-loader
hugegraph-spark-connector		hugegraph-spark-connector
hugegraph-tools		hugegraph-tools
tools		tools
.asf.yaml		.asf.yaml
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.licenserc.yaml		.licenserc.yaml
AGENTS.md		AGENTS.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
pom.xml		pom.xml

Navigation Menu

Uh oh!

Repository files navigation

hugegraph-toolchain

What is HugeGraph Toolchain?

Related Projects

Architecture Overview

Quick Start

Prerequisites

Choose Your Path

Docker Quick Start

Module Overview

hugegraph-client

Other Client SDKs

hugegraph-loader

hugegraph-hubble

hugegraph-tools

hugegraph-spark-connector

Maven Dependencies

Build & Development

Full Build

Module-Specific Builds

Running Tests

Code Style

Docker

Documentation

Contributing

Community & Contact

License

About

Releases

Packages

Used by

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

hugegraph-toolchain

What is HugeGraph Toolchain?

Related Projects

Architecture Overview

Quick Start

Prerequisites

Choose Your Path

Docker Quick Start

Module Overview

hugegraph-client

Other Client SDKs

hugegraph-loader

hugegraph-hubble

hugegraph-tools

hugegraph-spark-connector

Maven Dependencies

Build & Development

Full Build

Module-Specific Builds

Running Tests

Code Style

Docker

Documentation

Contributing

Community & Contact

License

About

Topics

Resources

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages