Skip to content
BranchesTags

Repository files navigation

hugegraph-toolchain

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

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.

Hubble's primary authentication and connection design targets HugeGraph 1.8/master: PD discovery supplies the server address, anonymous mode uses a real unauthenticated client, and account/GraphSpace permissions are reduced to four readable presets. A thin adapter keeps 1.7 usable and limits 1.5 to its standalone core graph workflow; version checks are centralized rather than spread across UI pages.

Hubble Workbench

Hubble brings graph exploration, schema preparation, asynchronous analysis, and distributed cluster operations into one workspace.

HugeGraph Hubble workbench

Distributed Operations

The cluster overview keeps service topology, node health, source status, and capacity facts in one operational view.

HugeGraph Hubble cluster overview

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

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

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 -.->|PD discovery UI| PD

    LOADER -.->|Sources| SRC["CSV | JSON | HDFS<br/>MySQL | Kafka"]
    SPARK -.->|I/O| SPK["Spark DataFrames"]

    style distributed stroke-dasharray: 5 5
Loading
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:

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

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

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: 120 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!

contributors graph

Community & Contact

WeChat QR code

License

hugegraph-toolchain is licensed under Apache 2.0 License.

About

HugeGraph toolchain - include a series useful graph modules

hugegraph.apache.org/

Topics

apacheclientgraphhugegraphtool

Resources

Readme
Apache-2.0 license

Code of conduct

Code of conduct

Security policy

Security policy
Activity
Custom properties

Stars

120 stars

Watchers

17 watching

Forks

124 forks
Report repository

Releases

Packages

Used by

Contributors

Languages