Google Git
Sign in
apache/hugegraph-toolchain/refs/heads/master
commit
49fa7180496fa126d3fa848094d316a546dbb689
[log] [tgz]
author
imbajin <jin@apache.org>
Sun Feb 01 20:14:25 2026 +0800
committer
GitHub <noreply@github.com>
Sun Feb 01 20:14:25 2026 +0800
tree
5fcf2f733d9fc0f9e8bd94baf4643918f2b0450d
parent
f58194b69dc990bcf5fde6becc74ef25873a8c94 [diff]
doc: add AGENTS.md, update README and project config (#711)

* doc: add AGENTS.md, update README and project config

Add AGENTS.md with guidance for AI coding assistants and repository build/run commands. Expand and reorganize README: add architecture diagrams, detailed module overviews, quick start, Docker examples, build/test commands, and bump example dependency versions to 1.7.0. Update .serena/project.yml to include project_name and placeholder settings for included tools, modes, and fixed_tools to better configure Serena project metadata.

* Update README.md

* Update README.md

* Disable Serena modes; tweak Maven commands

Set base_modes and default_modes to empty lists in .serena/project.yml to disable project-level base/default modes. Update README Maven invocation: add -e to the client compile for extended error output and add -ntp to Hubble-related mvn commands to suppress transfer progress and align flags across examples.
3 files changed
tree: 5fcf2f733d9fc0f9e8bd94baf4643918f2b0450d
  1. .github/
  2. .idea/
  3. .serena/
  4. assembly/
  5. hugegraph-client/
  6. hugegraph-client-go/
  7. hugegraph-dist/
  8. hugegraph-hubble/
  9. hugegraph-loader/
  10. hugegraph-spark-connector/
  11. hugegraph-tools/
  12. tools/
  13. .asf.yaml
  14. .editorconfig
  15. .gitattributes
  16. .gitignore
  17. .licenserc.yaml
  18. AGENTS.md
  19. DISCLAIMER
  20. LICENSE
  21. NOTICE
  22. pom.xml
  23. README.md
README.md

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.

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

Quick Start

Prerequisites

RequirementVersionNotes
JDK11+LTS recommended
Maven3.6+For building from source
HugeGraph Server1.5.0+Required for client/loader

Choose Your Path

I want to...Use ThisGet Started
Visualize graphs via Web UIHubbleDocker: docker run -p 8088:8088 hugegraph/hugegraph-hubble
Load CSV/JSON data into graphLoaderCLI with JSON mapping config (docs)
Build a Java app with HugeGraphClientMaven dependency (example)
Backup/restore graphsToolsCLI commands (docs)
Process graphs with SparkSpark ConnectorDataFrame 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

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

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:

  • 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-incubating-*/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

ModuleBuild Command
Clientmvn -e compile -pl hugegraph-client -Dmaven.javadoc.skip=true -ntp
Loadermvn install -pl hugegraph-client,hugegraph-loader -am -DskipTests -ntp
Hubblemvn install -pl hugegraph-client,hugegraph-loader -am -DskipTests -ntp && cd hugegraph-hubble && mvn package -DskipTests -ntp
Toolsmvn install -pl hugegraph-client,hugegraph-tools -am -DskipTests -ntp
Sparkmvn install -pl hugegraph-client,hugegraph-spark-connector -am -DskipTests -ntp
Go Clientcd hugegraph-client-go && make all

Running Tests

ModuleTest TypeCommand
ClientUnit (no server)mvn test -pl hugegraph-client -Dtest=UnitTestSuite
ClientAPI (server needed)mvn test -pl hugegraph-client -Dtest=ApiTestSuite
ClientFunctionalmvn test -pl hugegraph-client -Dtest=FuncTestSuite
LoaderUnitmvn test -pl hugegraph-loader -P unit
LoaderFile sourcesmvn test -pl hugegraph-loader -P file
LoaderHDFSmvn test -pl hugegraph-loader -P hdfs
LoaderJDBCmvn test -pl hugegraph-loader -P jdbc
LoaderKafkamvn test -pl hugegraph-loader -P kafka
HubbleUnitmvn test -P unit-test -pl hugegraph-hubble/hubble-be
ToolsFunctionalmvn 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:

ImagePurposePort
hugegraph/hugegraph-hubbleWeb UI8088
hugegraph/hugegraph-loaderData 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
cd hugegraph-loader && docker build -t hugegraph/hugegraph-loader:latest .

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

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

License

hugegraph-toolchain is licensed under Apache 2.0 License.