GUIDES

• 1: HugeGraph Architecture Overview
• 2: HugeGraph Design Concepts
• 3: HugeGraph Plugin mechanism and plug-in extension process
• 4: HugeGraph Toolchain Local Testing Guide
• 5: Backup and Restore
• 6: HugeGraph Docker Cluster Guide
• 7: FAQ
• 8: Security Report

1 - HugeGraph Architecture Overview

1 Overview

As a full-stack graph system covering Graph Database, Graph Computing, and Graph AI, HugeGraph is centered around a high-performance graph engine (HugeGraph Server) and supports both OLTP and OLAP graph computation types. For the OLTP layer, it implements the Apache TinkerPop3 framework and supports the Gremlin and Cypher query languages. It comes with a complete application toolchain and provides a pluggable backend storage driver framework.

Below is the overall architecture diagram of HugeGraph:

HugeGraph consists of three layers of functionality: the application layer, the graph engine layer, and the storage layer.

• Application Layer:
  • Hubble: A one-stop visual analysis platform that covers the entire process from data modeling to rapid data import, online and offline analysis, and unified graph management, realizing wizard-style operations for the entire graph application process.
  • Loader: A data import component that can transform data from multiple data sources into graph vertices and edges and batch import them into the graph database.
  • Tools: Command-line tools for deploying, managing, and backing up/restoring data in HugeGraph.
  • Computer: A distributed graph processing system (OLAP), which is an implementation of Pregel and can run on Kubernetes.
  • Client: Client SDKs encapsulate the core operations for connecting to HugeGraph Server, managing schemas, reading and writing graph data, and running queries. HugeGraph currently provides Java, Python, and Go clients, while a Rust client is under development.
• Graph Engine Layer:
  • REST Server: Provides a RESTful API for querying graph/schema information, supports the Gremlin and Cypher query languages, and offers APIs for service monitoring and operations.
  • Graph Engine: Supports both OLTP and OLAP graph computation types, with OLTP implementing the Apache TinkerPop3 framework.
  • Backend Interface: Implements the storage of graph data to the backend.
• Storage Layer:
  • Storage Backend: Version 1.7.0 supports RocksDB, HStore, HBase, and Memory. Custom backends can be added through plugins.

2 - HugeGraph Design Concepts

1. Property Graph

There are two common graph data representation models, namely the RDF (Resource Description Framework) model and the Property Graph (Property Graph) model. Both RDF and Property Graph are the most basic and well-known graph representation modes, and both can represent entity-relationship modeling of various graphs. RDF is a W3C standard, while Property Graph is an industry standard and is widely supported by graph database vendors. HugeGraph currently uses Property Graph.

The storage concept model corresponding to HugeGraph is also designed with reference to Property Graph. For specific examples, see the figure below: ( This figure is outdated for the old version design, please ignore it and update it later )

Inside HugeGraph, each vertex/edge is identified by a unique VertexId/EdgeId, and the attributes are stored inside the corresponding vertex/edge. The relationship/mapping between vertices is stored through edges.

When the vertex attribute value is stored by edge pointer, if you want to update a vertex-specific attribute value, you can directly write it by overwriting. The disadvantage is that the VertexId is redundantly stored; if you want to update the attribute of the relationship, you need to use the read-and-modify method , read all attributes first, modify some attributes, and then write to the storage system, the update efficiency is low. According to experience, there are more requirements for modifying vertex attributes, but less for edge attributes. For example, calculations such as PageRank and Graph Cluster require frequent modification of vertex attribute values.

2. Graph Partition Scheme

For distributed graph databases, there are two partition storage methods for graphs: Edge Cut and Vertex Cut, as shown in the following figure. When using the Edge Cut method to store graphs, any vertex will only appear on one machine, while edges may be distributed on different machines. This storage method may lead to multiple storage of edges. When using the Vertex Cut method to store graphs, any edge will only appear on one machine, and each same point may be distributed to different machines. This storage method may result in multiple storage of vertices.

The EdgeCut partition scheme can support high-performance insert and update operations, while the VertexCut partition scheme is more suitable for static graph query analysis, so EdgeCut is suitable for OLTP graph query, and VertexCut is more suitable for OLAP graph query. HugeGraph currently adopts the partition scheme of EdgeCut.

3. VertexId Strategy

Vertex of HugeGraph supports four ID strategies. Different VertexLabels in the same graph database can use different Id strategies. Currently, the Id strategies supported by HugeGraph are:

• Automatic generation (AUTOMATIC): Use the Snowflake algorithm to automatically generate a globally unique Id, Long type;
• Primary Key (PRIMARY_KEY): Generate Id through VertexLabel+PrimaryKeyValues, String type;
• Custom (CUSTOMIZE_STRING|CUSTOMIZE_NUMBER): User-defined Id, which is divided into two types: String and Long, and you need to ensure the uniqueness of the Id yourself;
• Custom UUID (CUSTOMIZE_UUID): User-defined Id in UUID form, you need to ensure the uniqueness of the Id yourself;

The default Id policy is AUTOMATIC, if the user calls the primaryKeys() method and sets the correct PrimaryKeys, the PRIMARY_KEY policy is automatically enabled. After enabling the PRIMARY_KEY strategy, HugeGraph can implement data deduplication based on PrimaryKeys.

1. AUTOMATIC ID Policy

schema.vertexLabel("person")
     .useAutomaticId()
     .properties("name", "age", "city")
     .create();
graph.addVertex(T.label, "person","name", "marko", "age", 18, "city", "Beijing");

2. PRIMARY_KEY ID policy

schema.vertexLabel("person")
     .usePrimaryKeyId()
     .properties("name", "age", "city")
     .primaryKeys("name", "age")
     .create();
graph.addVertex(T.label, "person","name", "marko", "age", 18, "city", "Beijing");

3. CUSTOMIZE_STRING ID Policy

schema.vertexLabel("person")
     .useCustomizeStringId()
     .properties("name", "age", "city")
     .create();
graph.addVertex(T.label, "person", T.id, "123456", "name", "marko","age", 18, "city", "Beijing");

4. CUSTOMIZE_NUMBER ID Policy

schema.vertexLabel("person")
     .useCustomizeNumberId()
     .properties("name", "age", "city")
     .create();
graph.addVertex(T.label, "person", T.id, 123456, "name", "marko","age", 18, "city", "Beijing");

5. CUSTOMIZE_UUID ID Policy

schema.vertexLabel("person")
     .useCustomizeUuidId()
     .properties("name", "age", "city")
     .create();
graph.addVertex(T.label, "person", T.id, UUID.randomUUID(), "name", "marko","age", 18, "city", "Beijing");

If users need Vertex deduplication, there are three options:

1. Adopt PRIMARY_KEY strategy, automatic overwriting, suitable for batch insertion of large amount of data, users cannot know whether overwriting has occurred
2. Adopt AUTOMATIC strategy, read-and-modify, suitable for small data insertion, users can clearly know whether overwriting occurs
3. Using the CUSTOMIZE_STRING or CUSTOMIZE_NUMBER strategy, the user guarantees the uniqueness

4. EdgeId policy

The EdgeId of HugeGraph is composed of srcVertexId + edgeLabel + sortKey + tgtVertexId. Among them sortKey is an important concept of HugeGraph. There are two reasons for adding sortKey to Edge as the unique ID of Edge:

1. If there are multiple edges of the same Label between two vertices, they can be distinguished by sortKey
2. For SuperNode nodes, edges can be sorted and truncated by sortKey.

Since EdgeId is composed of srcVertexId + edgeLabel + sortKey + tgtVertexId, HugeGraph will automatically overwrite when the same Edge is inserted multiple times to achieve deduplication. It should be noted that the properties of Edge will also be overwritten in the batch insert mode.

In addition, because HugeGraph’s EdgeId adopts an automatic deduplication strategy, HugeGraph considers that there is only one edge in the case of self-loop (a vertex has an edge pointing to itself), while a graph database that uses the AUTOMATIC strategy (TitanDB for example) considers that the graph has two edges.

The edges of HugeGraph only support directed edges, and undirected edges can be realized by creating two edges, Out and In.

5. HugeGraph transaction overview

TinkerPop transaction overview

A TinkerPop transaction refers to a unit of work that performs operations on the database. A set of operations within a transaction either succeeds or all fail. For a detailed introduction, please refer to the official documentation of TinkerPop: http://tinkerpop.apache.org/docs/current/reference/#transactions

TinkerPop transaction interfaces

• open open transaction
• commit commit transaction
• rollback rollback transaction
• close closes the transaction

TinkerPop transaction specification

• The transaction must be explicitly committed before it can take effect (the modification operation can only be seen by the query in this transaction if it is not committed)
• A transaction must be opened before it can be committed or rolled back
• If the transaction setting is automatically turned on, there is no need to explicitly turn it on (the default method), if it is set to be turned on manually, it must be turned on explicitly
• When the transaction is closed, you can set three modes: automatic commit, automatic rollback (default mode), manual (explicit shutdown is prohibited), etc.
• The transaction must be closed after committing or rolling back
• The transaction must be open after the query
• Transactions (non-threaded tx) must be thread-isolated, and multi-threaded operations on the same transaction do not affect each other

For more transaction specification use cases, see: Transaction Test

HugeGraph transaction implementation

• All operations in a transaction either succeed or fail
• A transaction can only read what has been committed by another transaction (Read committed)
• All uncommitted operations can be queried in this transaction, including:
  • Adding a vertex can query the vertex
  • Delete a vertex to filter out the vertex
  • Deleting a vertex can filter out the related edges of the vertex
  • Adding an edge can query the edge
  • Delete edge can filter out the edge
  • Adding/modifying (vertex, edge) attributes can take effect when querying
  • Delete (vertex, edge) attributes can take effect at query time
• All uncommitted operations become invalid after the transaction is rolled back, including:
  • Adding and deleting vertices and edges
  • Addition/modification, deletion of attributes

Example: One transaction cannot read another transaction’s uncommitted content

    static void testUncommittedTx(final HugeGraph graph) throws InterruptedException {

        final CountDownLatch latchUncommit = new CountDownLatch(1);
        final CountDownLatch latchRollback = new CountDownLatch(1);

        Thread thread = new Thread(() -> {
            // this is a new transaction in the new thread
            graph.tx().open();

            System.out.println("current transaction operations");

            Vertex james = graph.addVertex(T.label, "author",
                                           "id", 1, "name", "James Gosling",
                                           "age", 62, "lived", "Canadian");
            Vertex java = graph.addVertex(T.label, "language", "name", "java",
                                          "versions", Arrays.asList(6, 7, 8));
            james.addEdge("created", java);

            // we can query the uncommitted records in the current transaction
            System.out.println("current transaction assert");
            assert graph.vertices().hasNext() == true;
            assert graph.edges().hasNext() == true;

            latchUncommit.countDown();

            try {
                latchRollback.await();
            } catch (InterruptedException e) {
                throw new RuntimeException(e);
            }

            System.out.println("current transaction rollback");
            graph.tx().rollback();
        });

        thread.start();

        // query none result in other transaction when not commit()
        latchUncommit.await();
        System.out.println("other transaction assert for uncommitted");
        assert !graph.vertices().hasNext();
        assert !graph.edges().hasNext();

        latchRollback.countDown();
        thread.join();

        // query none result in other transaction after rollback()
        System.out.println("other transaction assert for rollback");
        assert !graph.vertices().hasNext();
        assert !graph.edges().hasNext();
    }

Principle of transaction realization

• The server internally realizes isolation by binding transactions to threads (ThreadLocal)
• The uncommitted content of this transaction overwrites the old data in chronological order for this transaction to query the latest version of data
• The bottom layer relies on the back-end database to ensure transaction atomicity (for example, the batch interface of RocksDB guarantees atomicity)

Notice

The RESTful API does not expose the transaction interface for the time being

TinkerPop API allows open transactions, which are automatically closed when the request is completed (Gremlin Server forces close)

3 - HugeGraph Plugin mechanism and plug-in extension process

Background

1. HugeGraph is not only open source and open, but also simple and easy to use. General users can easily add plug-in extension functions without changing the source code.
2. HugeGraph supports a variety of built-in storage backends, and also allows users to extend custom backends without changing the existing source code.
3. HugeGraph supports full-text search. The full-text search function involves word segmentation in various languages. Currently, there are 7 built-in word breakers (ansj, hanlp, smartcn, jieba, jcseg, mmseg4j, ikanalyzer), and it also allows users to expand custom word breakers without changing the existing source code.

Scalable dimension

Currently, the plug-in method provides extensions in the following dimensions:

• backend storage
• serializer
• Custom configuration items
• tokenizer

Plug-in implementation mechanism

1. HugeGraph provides a plug-in interface HugeGraphPlugin, which supports plug-in through the Java SPI mechanism
2. HugeGraph provides four extension registration functions as static methods on HugeGraphPlugin: registerOptions(), registerBackend(), registerSerializer(), registerAnalyzer()
3. The plug-in implementer implements the corresponding Options, Backend, Serializer or Analyzer interface
4. The plug-in implementer implements register()the method of the HugeGraphPlugin interface, registers the specific implementation class listed in the above point 3 in this method, and packs it into a jar package
5. The plug-in user puts the jar package in the HugeGraph Server installation directory plugins, modifies the relevant configuration items to the plug-in custom value, and restarts to take effect

Plug-in implementation process example

1 Create a new maven project

1.1 Name the project name: hugegraph-plugin-demo

1.2 Add hugegraph-core Jar package dependencies

The details of maven pom.xml are as follows:

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>
    <groupId>org.apache.hugegraph</groupId>
    <artifactId>hugegraph-plugin-demo</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <name>hugegraph-plugin-demo</name>

    <dependencies>
        <dependency>
            <groupId>org.apache.hugegraph</groupId>
            <artifactId>hugegraph-core</artifactId>
            <version>${project.version}</version>
        </dependency>
    </dependencies>
</project>

2 Realize extended functions

2.1 Extending a custom backend

2.1.1 Implement the interface BackendStoreProvider

• Realizable interfaces: org.apache.hugegraph.backend.store.BackendStoreProvider
• Or inherit an abstract class:org.apache.hugegraph.backend.store.AbstractBackendStoreProvider

Take the RocksDB backend RocksDBStoreProvider as an example:

public class RocksDBStoreProvider extends AbstractBackendStoreProvider {

    protected String database() {
        return this.graph().toLowerCase();
    }

    @Override
    protected BackendStore newSchemaStore(HugeConfig config, String store) {
        return new RocksDBStore.RocksDBSchemaStore(this, this.database(), store);
    }

    @Override
    protected BackendStore newGraphStore(HugeConfig config, String store) {
        return new RocksDBStore.RocksDBGraphStore(this, this.database(), store);
    }

    @Override
    protected BackendStore newSystemStore(HugeConfig config, String store) {
        return new RocksDBStore.RocksDBSystemStore(this, this.database(), store);
    }

    @Override
    public String type() {
        return "rocksdb";
    }

    @Override
    public String driverVersion() {
        return "1.11";
    }
}

2.1.2 Implement interface BackendStore

The BackendStore interface is defined as follows:

public interface BackendStore {
    // Store name
    String store();

    // Stored version
    String storedVersion();

    // Database name
    String database();

    // Get the parent provider
    BackendStoreProvider provider();

    // Get the system schema store
    SystemSchemaStore systemSchemaStore();

    // Whether it is the storage of schema
    boolean isSchemaStore();

    // Open/close database
    void open(HugeConfig config);
    void close();
    boolean opened();

    // Initialize/clear database
    void init();
    void clear(boolean clearSpace);
    boolean initialized();

    // Delete all data of database (keep table structure)
    void truncate();

    // Add/delete data
    void mutate(BackendMutation mutation);

    // Query data
    Iterator<BackendEntry> query(Query query);
    Number queryNumber(Query query);

    // Transaction
    void beginTx();
    void commitTx();
    void rollbackTx();

    // Get metadata by key
    <R> R metadata(HugeType type, String meta, Object[] args);

    // Backend features
    BackendFeatures features();

    // Increase next id for specific type
    void increaseCounter(HugeType type, long increment);

    // Get current counter for a specific type
    long getCounter(HugeType type);
}

2.1.3 Extending custom serializers

The serializer must inherit the abstract class: org.apache.hugegraph.backend.serializer.AbstractSerializer ( implements GraphSerializer, SchemaSerializer) The main interface is defined as follows:

public interface GraphSerializer {
    BackendEntry writeVertex(HugeVertex vertex);
    BackendEntry writeOlapVertex(HugeVertex vertex);
    BackendEntry writeVertexProperty(HugeVertexProperty<?> prop);
    HugeVertex readVertex(HugeGraph graph, BackendEntry entry);
    BackendEntry writeEdge(HugeEdge edge);
    BackendEntry writeEdgeProperty(HugeEdgeProperty<?> prop);
    HugeEdge readEdge(HugeGraph graph, BackendEntry entry);
    CIter<Edge> readEdges(HugeGraph graph, BackendEntry bytesEntry);
    BackendEntry writeIndex(HugeIndex index);
    HugeIndex readIndex(HugeGraph graph, ConditionQuery query, BackendEntry entry);
    BackendEntry writeId(HugeType type, Id id);
    Query writeQuery(Query query);
}

public interface SchemaSerializer {
    BackendEntry writeVertexLabel(VertexLabel vertexLabel);
    VertexLabel readVertexLabel(HugeGraph graph, BackendEntry entry);
    BackendEntry writeEdgeLabel(EdgeLabel edgeLabel);
    EdgeLabel readEdgeLabel(HugeGraph graph, BackendEntry entry);
    BackendEntry writePropertyKey(PropertyKey propertyKey);
    PropertyKey readPropertyKey(HugeGraph graph, BackendEntry entry);
    BackendEntry writeIndexLabel(IndexLabel indexLabel);
    IndexLabel readIndexLabel(HugeGraph graph, BackendEntry entry);
}

2.1.4 Extend custom configuration items

When adding a custom backend, it may be necessary to add new configuration items. The implementation process mainly includes:

• Add a configuration item container class and implement the interface org.apache.hugegraph.config.OptionHolder
• Provide a singleton method public static OptionHolder instance(), and call the method when the object is initialized OptionHolder.registerOptions()
• Add configuration item declaration, single-value configuration item type is ConfigOption, multi-value configuration item type is ConfigListOption

Take the RocksDB configuration item definition as an example:

public class RocksDBOptions extends OptionHolder {

    private RocksDBOptions() {
        super();
    }

    private static volatile RocksDBOptions instance;

    public static synchronized RocksDBOptions instance() {
        if (instance == null) {
            instance = new RocksDBOptions();
            instance.registerOptions();
        }
        return instance;
    }

    public static final ConfigOption<String> DATA_PATH =
            new ConfigOption<>(
                    "rocksdb.data_path",
                    "The path for storing data of RocksDB.",
                    disallowEmpty(),
                    "rocksdb-data/data"
            );

    public static final ConfigOption<String> WAL_PATH =
            new ConfigOption<>(
                    "rocksdb.wal_path",
                    "The path for storing WAL of RocksDB.",
                    disallowEmpty(),
                    "rocksdb-data/wal"
            );

    public static final ConfigListOption<String> DATA_DISKS =
            new ConfigListOption<>(
                    "rocksdb.data_disks",
                    false,
                    "The optimized disks for storing data of RocksDB. " +
                    "The format of each element: `STORE/TABLE: /path/disk`." +
                    "Allowed keys are [g/vertex, g/edge_out, g/edge_in, " +
                    "g/vertex_label_index, g/edge_label_index, " +
                    "g/range_int_index, g/range_float_index, " +
                    "g/range_long_index, g/range_double_index, " +
                    "g/secondary_index, g/search_index, g/shard_index, " +
                    "g/unique_index, g/olap]",
                    null,
                    String.class,
                    ImmutableList.of()
            );
}

2.2 Extend custom tokenizer

The tokenizer needs to implement the interface org.apache.hugegraph.analyzer.Analyzer, take implementing a SpaceAnalyzer space tokenizer as an example.

package org.apache.hugegraph.plugin;

import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;

import org.apache.hugegraph.analyzer.Analyzer;

public class SpaceAnalyzer implements Analyzer {

    @Override
    public Set<String> segment(String text) {
        return new HashSet<>(Arrays.asList(text.split(" ")));
    }
}

3. Implement the plug-in interface and register it

The plug-in registration entry is HugeGraphPlugin.register(), the custom plug-in must implement this interface method, and register the extension items defined above inside it. The interface org.apache.hugegraph.plugin.HugeGraphPlugin is defined as follows:

public interface HugeGraphPlugin {

    String name();

    void register();

    String supportsMinVersion();

    String supportsMaxVersion();
}

And HugeGraphPlugin provides 4 static methods for registering extensions:

• registerOptions(String name, String classPath): register configuration items
• registerBackend(String name, String classPath): register backend (BackendStoreProvider)
• registerSerializer(String name, String classPath): register serializer
• registerAnalyzer(String name, String classPath): register tokenizer

The following is an example of registering the SpaceAnalyzer tokenizer:

package org.apache.hugegraph.plugin;

public class DemoPlugin implements HugeGraphPlugin {

    @Override
    public String name() {
        return "demo";
    }

    @Override
    public void register() {
        HugeGraphPlugin.registerAnalyzer("demo", SpaceAnalyzer.class.getName());
    }

    @Override
    public String supportsMinVersion() {
        return "1.7.0";
    }

    @Override
    public String supportsMaxVersion() {
        return "1.8.0";
    }
}

4. Configure SPI entry

1. Make sure the services directory exists: hugegraph-plugin-demo/resources/META-INF/services
2. Create a text file in the services directory: org.apache.hugegraph.plugin.HugeGraphPlugin
3. The content of the file is as follows: org.apache.hugegraph.plugin.DemoPlugin

5. Make Jar package

Through maven packaging, execute the command in the project directory mvn package, and a Jar package file will be generated in the target directory. Copy the Jar package to the plugins directory when using it, and restart the service to take effect.

4 - HugeGraph Toolchain Local Testing Guide

This guide helps developers run HugeGraph toolchain tests locally.

1. Core Concepts

1.1 Core Dependency: HugeGraph Server

Integration and functional tests of the toolchain depend on HugeGraph Server, including Client, Loader, Hubble, Spark Connector, Tools, and other components.

1.2 Test Types

• Unit Tests: Test individual functions/methods, no external dependencies required
• API Tests (ApiTestSuite): Test API interfaces, requires running HugeGraph Server
• Functional Tests (FuncTestSuite): End-to-end tests, require complete system environment

2. Environment Setup

2.1 System Requirements

• Operating System: Linux / macOS (Windows use WSL2)
• JDK: >= 11, configure JAVA_HOME
• Maven: >= 3.6
• Python: >= 3.11 (only required for Hubble tests)

2.2 Clone Code

git clone https://github.com/apache/hugegraph-toolchain.git
cd hugegraph-toolchain

3. Deploy Test Environment

Deployment Options

• Script Deployment: Specify a Server commit to reproduce the server version used by CI
• Docker Deployment: Suitable for quick checks; if tests fail, first verify compatibility between the image and Toolchain

For detailed installation instructions, refer to Community Documentation

3.1 Script Deployment

Parameter Description

• $COMMIT_ID: Specify Server source code Git Commit ID
• $DB_DATABASE / $DB_PASS: MySQL database name and password for Loader JDBC tests

Deployment Steps

1. Install HugeGraph Server

# Set the Server baseline; use a full commit SHA for reproducible results
export COMMIT_ID="master"

# Execute installation (script located in /assembly/travis/ directory)
hugegraph-client/assembly/travis/install-hugegraph-from-source.sh $COMMIT_ID

• The script starts HTTP and HTTPS instances on ports 8080 and 8443 and configures admin/pa authentication.
• Ensure both ports are available before running it.

2. Install Optional Dependencies

# Hadoop (only required for Loader HDFS tests)
hugegraph-loader/assembly/travis/install-hadoop.sh

# MySQL (only required for Loader JDBC tests)
hugegraph-loader/assembly/travis/install-mysql.sh $DB_DATABASE $DB_PASS

3. Health Check

curl -u admin:pa http://localhost:8080/graphspaces/DEFAULT/graphs
# Returns {"graphs":["hugegraph"]} indicates success

3.2 Docker Deployment

Note: Docker images may have version lag, use script deployment if encountering compatibility issues

Quick Start

docker network create hugegraph-net
docker run -itd --name=server -p 8080:8080 --network hugegraph-net hugegraph/hugegraph:latest

docker-compose Configuration (Optional)

Complete configuration example including Server, MySQL, Hadoop services (requires Docker Compose V2):

version: '3.8'

services:
  hugegraph-server:
    image: hugegraph/hugegraph:latest  # Can be replaced with a specific version, or build your own image
    container_name: hugegraph-server
    ports:
      - "8080:8080"  # HugeGraph Server HTTP port
    environment:
      # Configure HugeGraph Server parameters as needed, e.g., backend storage
      - HUGEGRAPH_SERVER_OPTIONS="-Dstore.backend=rocksdb"
    volumes:
      # If you need to persist data or mount configuration files, add volumes here
      # - ./hugegraph-data:/opt/hugegraph/data
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8080/graphspaces/DEFAULT/graphs || exit 1"]
      interval: 10s
      timeout: 3s
      retries: 5
    networks:
      - hugegraph-net
  
  # If you need JDBC tests for hugegraph-loader, you can add the following service
  #   mysql:
  #     image: mysql:5.7
  #     container_name: mysql-db
  #     environment:
  #       MYSQL_ROOT_PASSWORD: ${DB_PASS:-your_mysql_root_password} # Read from environment variable, or use default
  #       MYSQL_DATABASE: ${DB_DATABASE:-hugegraph_test_db} # Read from environment variable, or use default
  #     ports:
  #       - "3306:3306"
  #     volumes:
  #       - ./mysql-data:/var/lib/mysql # Data persistence
  #     healthcheck:
  #       test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-p${DB_PASS:-your_mysql_root_password}"]
  #       interval: 5s
  #       timeout: 3s
  #       retries: 5
  #     networks:
  #       - hugegraph-net

  # If you need Hadoop/HDFS tests for hugegraph-loader, you can add the following services
  #   namenode:
  #     image: johannestang/hadoop-namenode:2.0.0-hadoop2.8.5-java8
  #     container_name: namenode
  #     ports:
  #       - "0.0.0.0:9870:9870"
  #       - "0.0.0.0:8020:8020"
  #     environment:
  #       - CLUSTER_NAME=test-cluster
  #       - HDFS_NAMENODE_USER=root
  #       - HADOOP_CONF_DIR=/hadoop/etc/hadoop
  #     volumes:
  #       - ./config/core-site.xml:/hadoop/etc/hadoop/core-site.xml
  #       - ./config/hdfs-site.xml:/hadoop/etc/hadoop/hdfs-site.xml
  #       - namenode_data:/hadoop/dfs/name
  #     command: bash -c "if [ ! -d /hadoop/dfs/name/current ]; then hdfs namenode -format; fi && /entrypoint.sh"
  #     healthcheck:
  #       test: ["CMD", "hdfs", "dfsadmin", "-report"]
  #       interval: 5s
  #       timeout: 3s
  #       retries: 5
  #     networks:
  #       - hugegraph-net

  #   datanode:
  #     image: johannestang/hadoop-datanode:2.0.0-hadoop2.8.5-java8
  #     container_name: datanode
  #     depends_on:
  #       - namenode
  #     environment:
  #       - CLUSTER_NAME=test-cluster
  #       - HDFS_DATANODE_USER=root
  #       - HADOOP_CONF_DIR=/hadoop/etc/hadoop
  #     volumes:
  #       - ./config/core-site.xml:/hadoop/etc/hadoop/core-site.xml
  #       - ./config/hdfs-site.xml:/hadoop/etc/hadoop/hdfs-site.xml
  #       - datanode_data:/hadoop/dfs/data
  #     healthcheck:
  #       test: ["CMD", "hdfs", "dfsadmin", "-report"]
  #       interval: 5s
  #       timeout: 3s
  #       retries: 5
  #     networks:
  #       - hugegraph-net

networks:
  hugegraph-net:
    driver: bridge
volumes:
  namenode_data:
  datanode_data:

Hadoop Configuration Mounts

Create a ./config folder in the same directory as docker-compose.yml to mount Hadoop configuration files. You can skip this step if HDFS testing is not required.

📁 ./config/core-site.xml content:

<configuration>
    <property>
        <name>fs.defaultFS</name>
        <value>hdfs://namenode:8020</value>
    </property>
</configuration>

📁 ./config/hdfs-site.xml content:

<configuration>
    <property>
        <name>dfs.namenode.name.dir</name>
        <value>/hadoop/hdfs/name</value>
    </property>
    <property>
        <name>dfs.datanode.data.dir</name>
        <value>/hadoop/hdfs/data</value>
    </property>
    <property>
        <name>dfs.permissions.superusergroup</name>
        <value>hadoop</value>
    </property>
    <property>
        <name>dfs.support.append</name>
        <value>true</value>
    </property>
</configuration>

Docker Operations

# Start services
docker compose up -d

# Check status
docker compose ps
lsof -i:8080  # Server
lsof -i:8020  # Hadoop
lsof -i:3306  # MySQL

# Stop services
docker compose down

4. Run Tests

Test process for each tool:

4.1 hugegraph-client

Compile

mvn -e compile -pl hugegraph-client -Dmaven.javadoc.skip=true -ntp

Dependent Services

Start HugeGraph Server (refer to Section 3)

Server Authentication Configuration

ApiTest requires authentication. No additional configuration is needed when using the script in Section 3.1. For a manually deployed Server, the authentication settings and test credentials must match the test code.

# 1. Modify authentication mode
cp conf/rest-server.properties conf/rest-server.properties.backup
sed -i 's|#auth.authenticator=.*|auth.authenticator=org.apache.hugegraph.auth.StandardAuthenticator|' conf/rest-server.properties
grep auth.authenticator conf/rest-server.properties
sed -i 's|gremlin.graph=org.apache.hugegraph.HugeFactory|gremlin.graph=org.apache.hugegraph.auth.HugeFactoryAuthProxy|' conf/graphs/hugegraph.properties

# 2. Set password
# Note: Test code uses "pa" as default password, must match for tests to work
bin/stop-hugegraph.sh
export PASSWORD="pa"  # Set to test default password
echo -e "${PASSWORD}" | bin/init-store.sh
bin/start-hugegraph.sh

Run Tests

# Check environment
curl -u admin:pa http://localhost:8080/graphspaces/DEFAULT/graphs

# Run tests
cd hugegraph-client
mvn test -Dtest=UnitTestSuite -ntp      # Unit tests
mvn test -Dtest=ApiTestSuite -ntp       # API tests (requires Server)
mvn test -Dtest=FuncTestSuite -ntp      # Functional tests (requires Server)

Check Server log if tests fail: logs/hugegraph-server.log

4.2 hugegraph-loader

Compile

mvn install -pl hugegraph-client,hugegraph-loader -am -Dmaven.javadoc.skip=true -DskipTests -ntp

Dependent Services

• Required: HugeGraph Server
• Optional: Hadoop (HDFS tests), MySQL (JDBC tests)

Run Tests

cd hugegraph-loader
mvn test -P unit -ntp   # Unit tests
mvn test -P file -ntp   # File tests (requires Server)
mvn test -P hdfs -ntp   # HDFS tests (requires Server + Hadoop)
mvn test -P jdbc -ntp   # JDBC tests (requires Server + MySQL)
mvn test -P kafka -ntp  # Kafka tests (requires Server)

4.3 hugegraph-hubble

Compile

mvn install -pl hugegraph-client,hugegraph-loader -am -Dmaven.javadoc.skip=true -DskipTests -ntp
cd hugegraph-hubble
mvn -e compile -Dmaven.javadoc.skip=true -ntp

Dependent Services

1. Start Server (refer to Section 3)

2. Python Environment

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
python -m pip install -r hubble-dist/assembly/travis/requirements.txt

3. Build and Verify

mvn package -Dmaven.test.skip=true
# Optional: Start and verify
cd apache-hugegraph-hubble*/bin
./start-hubble.sh -d && sleep 10
curl http://localhost:8088/actuator/health
./stop-hubble.sh

Run Tests

# Unit tests
mvn test -P unit-test -pl hugegraph-hubble/hubble-be -ntp

# Legacy Python API tests (requires Server; the script installs and starts Hubble)
curl -u admin:pa http://localhost:8080/graphspaces/DEFAULT/graphs  # Check Server
cd hugegraph-hubble
./hubble-dist/assembly/travis/run-api-test.sh

# Full verification entry point used by current CI (build the Hubble tarball first)
HUBBLE_TARBALL="$(ls target/apache-hugegraph-hubble-*.tar.gz | head -n 1)"
hubble-dist/assembly/travis/verify-hubble-issue-694.sh \
  "$HUBBLE_TARBALL" http://127.0.0.1:8080

4.4 hugegraph-spark-connector

Compile

mvn install -pl hugegraph-client,hugegraph-spark-connector -am -Dmaven.javadoc.skip=true -DskipTests -ntp

Run Tests

cd hugegraph-spark-connector
mvn test -ntp  # Requires Server running

4.5 hugegraph-tools

Compile

mvn install -pl hugegraph-client,hugegraph-tools -am -Dmaven.javadoc.skip=true -DskipTests -ntp

Run Tests

cd hugegraph-tools
mvn test -Dtest=FuncTestSuite -ntp  # Requires Server running

5. Common Issues

Service Connection Issues

If Server, MySQL, or Hadoop cannot be reached:

• Confirm services are running (Server must be on port 8080)
• Check port usage: lsof -i:8080
• Docker check: docker compose ps and docker compose logs

Configuration Issues

If files cannot be found or parameters are invalid:

• Check environment variables: echo $COMMIT_ID
• Script permissions: chmod +x hugegraph-*/assembly/travis/*.sh

HDFS Test Failures

• Confirm NameNode/DataNode running normally
• Check Hadoop logs
• Verify HDFS connection: hdfs dfsadmin -report

JDBC Test Failures

• Confirm MySQL running normally
• Verify database connection: mysql -u root -p$DB_PASS
• Check MySQL logs

6. References

• HugeGraph GitHub Repository: https://github.com/apache/hugegraph
• HugeGraph Toolchain GitHub Repository: https://github.com/apache/hugegraph-toolchain
• HugeGraph Server Documentation: https://hugegraph.apache.org/docs/quickstart/hugegraph/hugegraph-server/
• CI Configuration: .github/workflows/*-ci.yml
• Dependency Installation Scripts: hugegraph-*/assembly/travis/

5 - Backup and Restore

Description

Backup and Restore are functions of backup map and restore map. The data backed up and restored includes metadata (schema) and graph data (vertex and edge).

Backup

Export the metadata and graph data of a graph in the HugeGraph system in JSON format.

Restore

Re-import the data in JSON format exported by Backup to a graph in the HugeGraph system.

Restore has two modes:

• In Restoring mode, the metadata and graph data exported by Backup are restored to the HugeGraph system intact. It can be used for graph backup and recovery, and the general target graph is a new graph (without metadata and graph data). for example:
  • System upgrade, first back up the map, then upgrade the system, and finally restore the map to the new system
  • Graph migration, from a HugeGraph system, use the Backup function to export the graph, and then use the Restore function to import the graph into another HugeGraph system
• In the Merging mode, the metadata and graph data exported by Backup are imported into another graph that already has metadata or graph data. During the process, the ID of the metadata may change, and the IDs of vertices and edges will also change accordingly.
  • Can be used to merge graphs

Instructions

You can use hugegraph-tools to backup and restore the graph.

Backup

bin/hugegraph backup -t all -d data

This command backs up all the metadata and graph data of the hugegraph graph of http://127.0.0.1:8080 (the default –url) to the data directory.

Backup works in any graph mode, it does not check the graph mode

Restore

Restore has two modes: RESTORING and MERGING. Before restore, you must first set the graph mode according to your needs, the restore command fails when the graph is in any other mode.

Step 1: View and set graph mode

bin/hugegraph graph-mode-get

This command is used to view the current graph mode, including: NONE, RESTORING, MERGING, LOADING.

bin/hugegraph graph-mode-set -m RESTORING

This command is used to set the graph mode. Before Restore, it can be set to RESTORING or MERGING mode. In the example, it is set to RESTORING.

Step 2: Restore data

bin/hugegraph restore -t all -d data

This command re-imports all metadata and graph data in the data directory to the hugegraph graph at http://127.0.0.1:8080.

Step 3: Restoring Graph Mode

bin/hugegraph graph-mode-set -m NONE

This command is used to restore the graph mode to NONE.

So far, a complete graph backup and graph recovery process is over.

help

For detailed usage of backup and restore commands, please refer to the hugegraph-tools documentation.

API description for Backup/Restore usage and implementation

Backup

Backup uses the corresponding list(GET) API export of metadata and graph data, and no new API is added.

Restore

Restore uses the corresponding create(POST) API imports for metadata and graph data, and does not add new APIs.

There are two different modes for Restore: Restoring and Merging. In addition, there is a regular mode of NONE (default), the differences are as follows:

• In None mode, the writing of metadata and graph data is normal, please refer to the function description. special:
  • ID is not allowed when metadata (schema) is created
  • Graph data (vertex) is not allowed to specify an ID when the id strategy is Automatic
• Restoring mode, restoring to a new graph, in particular:
  • ID is allowed to be specified when metadata (schema) is created
  • Graph data (vertex) allows specifying an ID when the id strategy is Automatic
• Merging mode, merging into a graph with existing metadata and graph data, in particular:
  • ID is not allowed when metadata (schema) is created
  • Graph data (vertex) allows specifying an ID when the id strategy is Automatic

Normally, the graph mode is None. When you need to restore the graph, you need to temporarily change the graph mode to Restoring mode or Merging mode as needed, and when the Restore is completed, restore the graph mode to None.

The implemented RESTful API for setting graph mode is as follows:

View the schema of a graph. This operation requires administrator privileges

Method & Url

GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/mode

Response Status

200

Response Body

{
    "mode": "NONE"
}

Legal graph modes include: NONE, RESTORING, MERGING, LOADING

Set the mode of a graph. This operation requires administrator privileges

Method & Url

PUT http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/mode

Request Body

"RESTORING"

Legal graph modes include: NONE, RESTORING, MERGING, LOADING

Response Status

200

Response Body

{
    "mode": "RESTORING"
}

6 - HugeGraph Docker Cluster Guide

Overview

HugeGraph can quickly run a full distributed deployment (PD + Store + Server) with Docker Compose. This works on Linux and Mac.

Prerequisites

• Docker Engine 20.10+ or Docker Desktop 4.x+
• Docker Compose v2
• For a 3-node cluster on Mac: allocate at least 12 GB memory (Settings → Resources → Memory). Adjust this on other platforms as needed.

Tested environments: Linux (native Docker) and macOS (Docker Desktop with ARM M4).

Compose Files

Four compose files are available in the docker/ directory of the HugeGraph main repository:

The standalone topology uses hugegraph/hugegraph:${HUGEGRAPH_VERSION:-latest}. The HStore topologies use the matching hugegraph/pd, hugegraph/store, and hugegraph/server tags. Hubble is selected independently with ${HUBBLE_IMAGE:-hugegraph/hubble:latest}.

Note: The following steps assume you have already cloned or pulled the HugeGraph main repository locally, or at least have its docker/ directory available.

Authentication Environment

All topologies read the administrator password and the shared JWT secret from the Compose environment, normally a docker/.env file:

HUGEGRAPH_ADMIN_PASSWORD='replace-with-your-password'
HUGEGRAPH_AUTH_TOKEN_SECRET='<32 random bytes, for example openssl rand -hex 32>'

A non-empty HUGEGRAPH_ADMIN_PASSWORD enables Server authentication, and Hubble detects that mode through the Server API. Omitting it, or setting it to an empty value, disables authentication, which is only suitable for a trusted local environment. Keeping the same JWT secret preserves tokens when containers are recreated, and every Server replica in a multi-Server topology receives the same secret. The HA topology sets HG_SERVER_REQUIRE_AUTH_TOKEN_SECRET: "true", so it fails fast when a password is supplied without the shared secret. Do not commit .env.

HUGEGRAPH_ADMIN_PASSWORD initializes the built-in admin account on the first authenticated startup. Changing it later does not rotate an existing password, use the user API for that.

Single-Node Quickstart

cd hugegraph/docker
# Keep the version aligned with the latest release, for example 1.x.0
HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose.yml up -d --wait

Verify:

curl http://localhost:8080/versions
curl http://localhost:8088/about        # Hubble

Hubble is published on host loopback (127.0.0.1:8088) by default. Set HUBBLE_PUBLISH_HOST only behind an HTTPS reverse proxy and trusted network controls.

Minimal HStore Quickstart

cd hugegraph/docker
HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-hstore.yml up -d --wait

Verify:

curl http://localhost:8620/v1/health    # PD
curl http://localhost:8520/v1/health    # Store
curl http://localhost:8080/versions     # Server
curl http://localhost:8088/about        # Hubble

To build this topology from local source instead of pulling images, add the development overlay and keep both files on every later lifecycle command:

docker compose -f docker-compose-hstore.yml -f docker-compose.dev.yml up -d --build --wait

3-Node Cluster Quickstart

cd hugegraph/docker
HUGEGRAPH_VERSION=1.7.0 docker compose -f docker-compose-3pd-3store-3server.yml up -d --wait

Built-in startup ordering:

1. PD nodes start first and must pass the /v1/health check
2. Store nodes start only after all PD nodes are healthy
3. Server nodes start last, after all PD and Store nodes are healthy

Verify that the cluster is healthy:

curl http://localhost:8620/v1/health      # PD health
curl http://localhost:8520/v1/health      # Store health
curl http://localhost:8080/versions        # Server
curl http://localhost:8620/v1/stores       # Registered stores
curl http://localhost:8620/v1/partitions   # Partition assignment

With authentication on, a graph listing must reject an anonymous request and accept the administrator:

curl -o /dev/null -w '%{http_code}\n' \
  http://localhost:8080/graphspaces/DEFAULT/graphs                      # expect 401
curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \
  http://localhost:8080/graphspaces/DEFAULT/graphs                      # expect 200

The other two Servers answer on 8081 and 8082, and the other PD and Store nodes on 8621/8622 and 8521/8522.

Environment Variable Reference

The PD and Store entrypoints turn their variables into a SPRING_APPLICATION_JSON document and log the effective values at startup, so docker logs shows exactly what a container resolved. The Server entrypoint instead rewrites keys in conf/graphs/hugegraph.properties and conf/rest-server.properties.

PD Variables

Deprecated aliases: GRPC_HOST → HG_PD_GRPC_HOST, RAFT_ADDRESS → HG_PD_RAFT_ADDRESS, RAFT_PEERS → HG_PD_RAFT_PEERS_LIST, PD_INITIAL_STORE_LIST → HG_PD_INITIAL_STORE_LIST. A deprecated name is mapped to the new one only when the new one is unset, and the entrypoint logs a warning. The entrypoint exits with code 2 when any required variable is missing.

Store Variables

Deprecated aliases: PD_ADDRESS → HG_STORE_PD_ADDRESS, GRPC_HOST → HG_STORE_GRPC_HOST, RAFT_ADDRESS → HG_STORE_RAFT_ADDRESS

Server Variables

Unlike PD and Store, the Server entrypoint requires nothing: every variable below is optional and only the ones that are set are written into the config files. A distributed deployment still needs at least HG_SERVER_BACKEND and HG_SERVER_PD_PEERS.

wait-storage.sh waits up to 300 seconds for a store in state Up. That budget is fixed in the script and cannot be raised from the environment.

Deprecated aliases: BACKEND → HG_SERVER_BACKEND, PD_PEERS → HG_SERVER_PD_PEERS

HG_SERVER_INIT_STORE_ENABLED accepts only the spellings HugeConfig accepts, case-insensitively: y, t, yes, on, true, n, f, no, off, false. Anything else, 0 and 1 included, aborts the entrypoint.

The entrypoint writes docker/init_complete after a successful initialization and skips re-initialization on later startups, but still re-runs bin/init-store.sh so a disabled one revalidates its configuration on every start.

Compose Variables

These are read by the Compose files rather than by the entrypoints:

Port Reference

Ports published by the 3-node cluster:

The standalone topology publishes only 8080 and 8088. The minimal HStore topology publishes 8620 (PD REST), 8520 (Store REST), 8080, and 8088. PD Raft uses 8610 inside the network and is not published by any topology.

Troubleshooting

1. Containers exit due to OOM (exit code 137): Increase Docker Desktop memory to at least 12 GB, or reduce the JVM heap settings for the process that is being killed.

2. Raft leader election timeout: Check that HG_PD_RAFT_PEERS_LIST is identical on all PD nodes. Verify connectivity with docker exec hg-pd0 ping pd1.

3. Partition assignment does not complete: Check curl http://localhost:8620/v1/stores and confirm that all 3 stores show "state":"Up" before partition assignment can finish.

4. Connection refused: Ensure HG_* environment variables use container hostnames (pd0, store0) instead of 127.0.0.1.

5. Data survives a restart when you did not expect it to: docker compose down keeps the named volumes. Use docker compose down -v to delete the topology’s data as well.

Viewing runtime logs: Use docker logs <container-name> (e.g. docker logs hg-pd0) to view logs directly without exec-ing into the container. The standalone hugegraph/hugegraph image sets STDOUT_MODE=true, so its server log goes to the container stdout. The hugegraph/server (HStore) image does not, so docker logs on a Server of an HStore topology shows only the entrypoint output; read logs/hugegraph-server.log inside the container for the rest.

Container Supervision & Health Checks

Version note: This behavior is not present in the 1.7.0 images. Use HUGEGRAPH_VERSION=latest or wait for the next release tag.

Process Supervision Model

Previously, all three Docker entrypoints ended with tail -f /dev/null, which kept the container running even if the Java process crashed. Docker’s restart: unless-stopped policy never fired because the container never exited.

The entrypoints now supervise Java directly:

• PD and Store containers: the entrypoint passes -d false to the startup script, which execs Java directly. The container process IS the Java process: when Java exits (crash or clean shutdown), the container exits immediately and Docker’s restart policy fires.
• Server container: the entrypoint uses tail --pid=$PID -f /dev/null to block until Java exits. A SIGTERM/SIGINT trap forwards docker stop signals to Java and waits for clean shutdown (exits 0). If Java crashes, the entrypoint exits 1 so the restart policy fires.
• dumb-init (PID 1 in all images) forwards signals from Docker to the entrypoint process.

Server Startup Timeout

HG_SERVER_STARTUP_TIMEOUT_S controls how long the Server startup script waits for the REST service to respond. It defaults to 120 seconds when unset. The value must be a decimal integer without leading zeros, in the range 1–86400 seconds. An empty string, 0, a negative number, a fractional value, or an out-of-range value makes the entrypoint log an error and exit with code 1.

The entrypoint passes this value to bin/start-hugegraph.sh -t. If the Server is not ready within that wait or its process exits early, startup fails and the container exits with code 1; the configured restart policy may restart it. This budget does not include earlier storage initialization or waiting for the backend to become ready.

For example, from the HugeGraph repository’s docker/ directory, increase the standalone Server startup wait to 300 seconds (the Compose file forwards this variable to the container):

HG_SERVER_STARTUP_TIMEOUT_S=300 HUGEGRAPH_VERSION=latest \
  docker compose -f docker-compose.yml up -d --wait

This setting is independent of Docker health-check settings: start_period, interval, timeout, and retries. Those settings determine when the container is marked unhealthy; increasing only the health-check budget does not extend the Server startup script’s deadline. Changing this variable does not automatically adjust health checks either, so review both settings when startup is slow.

Health Check Endpoints

All four Docker images now include a HEALTHCHECK instruction. docker ps shows real health status. During the 90-second start period, failed checks do not count. After that, three consecutive failures mark the container as unhealthy.

The Compose files define their own health checks on top of these, so --wait and depends_on: condition: service_healthy work without relying on the image defaults. Those Compose checks use a shorter start period (30 to 120 seconds depending on the service and topology) and more retries.

Note: The -m true flag (cron-based monitor) in start-hugegraph.sh is for VM/bare-metal deployments only. It is not installed or used in Docker images. Docker users should rely on the built-in HEALTHCHECK and Docker’s restart policy instead.

7 - FAQ

• How to choose the back-end storage? RocksDB or distributed storage?

  HugeGraph supports multiple deployment modes. Choose based on your data scale and scenario:

  • Standalone Mode: Server + RocksDB, suitable for development/testing and small to medium-scale data (≤ 2 TB)
  • Distributed Mode: HugeGraph-PD + HugeGraph-Store (HStore), for deployments that require horizontal scaling and multiple replicas, supporting data scales up to 1 PB

  Version 1.7.0 supports RocksDB, HStore, HBase, and Memory. Legacy backends such as Cassandra, ScyllaDB, MySQL, and PostgreSQL require version 1.5.x or earlier.

• Prompt when starting the service: xxx (core dumped) xxx

  First confirm that the JDK version is Java 11 or later. HugeGraph 1.7.0 no longer supports Java 8.

• The service is started successfully, but there is a prompt similar to “Unable to connect to the backend or the connection is not open” when operating the graph

  Persistent local backends such as RocksDB and HBase must be initialized with init-store before their first startup. HStore is managed by PD and Store and does not use this script.

• Do all backends need to be executed before use init-store, and can the serialization options be filled in at will?

  Memory and HStore do not use init-store; persistent local backends such as RocksDB and HBase must be initialized before first use. The serializer must match the backend, for example RocksDB uses binary.

• Execution init-store error: Exception in thread "main" java.lang.UnsatisfiedLinkError: /tmp/librocksdbjni3226083071221514754.so: /usr/lib64/libstdc++.so.6: version `GLIBCXX_3.4.10' not found (required by /tmp/librocksdbjni3226083071221514754.so)

  RocksDB requires gcc 4.3.0 (GLIBCXX_3.4.10) and above

• The bin directory contains start-hugegraph.sh, start-restserver.sh and start-gremlinserver.sh. These scripts seem to be related to startup. Which one should be used?

  Current release packages retain only start-hugegraph.sh as the Server startup script. GremlinServer and the REST Server run in the same process.

• Two graphs are configured, the names are hugegraph and hugegraph1, and the command to start the service is start-hugegraph.sh. Is only the hugegraph graph opened?

  The script name is unrelated to the graph name. To load multiple local graphs from the graphs directory, set graph.load_from_local_config=true in rest-server.properties; its default value in the source code is false.

• After the service starts successfully, garbled characters are returned when using curl to query all vertices

  The batch vertices/edges returned by the server are compressed (gzip), and can be redirected to gunzip for decompression (curl http://example | gunzip), or can be sent with the postman of Firefox or the restlet plug-in of Chrome browser. request, the response data will be decompressed automatically.

• When using the vertex Id to query the vertex through the RESTful API, it returns empty, but the vertex does exist

  Check the type of the vertex ID. If it is a string type, the “id” part of the API URL needs to be enclosed in double quotes, while for numeric types, it is not necessary to enclose the ID in quotes.

• Vertex Id has been double quoted as required, but querying the vertex via the RESTful API still returns empty

  Check whether the vertex id contains +, space, /, ?, %, &, and = reserved characters of these URLs. If they exist, they need to be encoded. The following table gives the coded values:

  special character | encoded value
  ------------------| -------------
  +                 | %2B
  space             | %20
  /                 | %2F
  ?                 | %3F
  %                 | %25
  #                 | %23
  &                 | %26
  =                 | %3D

• Timeout when querying vertices or edges of a certain category (query by label)

  Since the amount of data belonging to a certain label may be relatively large, please add a limit limit.

• It is possible to operate the graph through the RESTful API, but when sending Gremlin statements, an error is reported: Request Failed(500)

  It may be that the configuration of GremlinServer is wrong, check whether the host and port of gremlin-server.yaml match the gremlinserver.url of rest-server.properties, if they do not match, modify them, and then Restart the service.

• When using Loader to import data, a Socket Timeout exception occurs, and then Loader is interrupted

  Continuously importing data will put too much pressure on the Server, which will cause some requests to time out. The pressure on Server can be appropriately relieved by adjusting the parameters of Loader (such as: number of retries, retry interval, error tolerance, etc.), and reduce the frequency of this problem.

• How to delete all data from a graph

  An administrator can call DELETE /graphspaces/{graphspace}/graphs/{graph}/clear?confirm_message=I'm sure to delete all data. The confirm_message query parameter must match that value exactly, otherwise the request is rejected. See the Graph API for details. This operation removes schemas, vertices, edges, and indexes.

• The database has been cleared and init-store has been executed, but when trying to add a schema, the prompt “xxx has existed” appeared.

  There is a cache in the HugeGraphServer, and it is necessary to restart the Server when the database is cleared, otherwise the residual cache will be inconsistent.

• An error is reported during the process of inserting vertices or edges: The max length of vertex id is 16384, but got xxx {yyy} or The max length of edge id is 65536, but got xxx {yyy}

  In order to ensure query performance, the current backend storage limits the length of the id column. The vertex id cannot exceed 16384 bytes and the edge id cannot exceed 65536 bytes. An index id longer than 32 bytes is stored as a hash instead of being rejected.

• Is there support for nested attributes, and if not, are there any alternatives?

  Nested attributes are currently not supported. Alternative: Nested attributes can be taken out as individual vertices and connected with edges.

• Can an EdgeLabel connect multiple pairs of VertexLabel, such as “investment” relationship, which can be “individual” investing in “enterprise”, or “enterprise” investing in “enterprise”?

  Yes. Call link(sourceLabel, targetLabel) once per pair when building the EdgeLabel; every pair is kept, so one “investment” label can cover both “individual” to “enterprise” and “enterprise” to “enterprise”. The older sourceLabel() and targetLabel() builder methods are deprecated and accept only a single pair.

• Prompt HTTP 415 Unsupported Media Type when sending a request through RestAPI

  Content-Type: application/json needs to be specified in the request header

Other issues can be searched in the issue area of the corresponding project, such as Server-Issues / Loader Issues

8 - Security Report

Reporting New Security Problems with Apache HugeGraph

⚠️ SEC Reminder: Notice to Vulnerability Researchers Regarding Graph Query Languages

Given the inherent parsing and execution flexibility of graph query languages (like Gremlin/Cypher), HugeGraph strongly recommends relying on the "Auth (Authentication) + IP Whitelist + Audit Log" mechanism in production environments to adhere to the Principle of Least Privilege. Furthermore, since Server nodes are essentially stateless, it is explicitly advised to use Containerized Environments (Docker/K8s) for isolated deployments in all production environments.

Recently, the community has received numerous security reports concerning the flexibility of graph queries. Until the overall HugeGraph security architecture is fully refactored, known situations involving the execution of DSL queries with Auth disabled or skipped, or by using an anonymous or unauthorized identity will no longer be treated individually as new vulnerabilities.

However, if a vulnerability can still be exploited in an environment where the Auth system is enabled by accessing it with an anonymous or unauthorized identity, or if one successfully bypasses the IP whitelist / escapes the container causing severe unauthorized access or underlying system destruction, we still consider this a high-risk security vulnerability and highly encourage you to report it to us at any time!

Adhering to the specifications of ASF, the HugeGraph community maintains a highly proactive and open attitude towards addressing security issues in the remediation projects.

We strongly recommend that users first report such issues to our dedicated security email list, with detailed procedures specified in the ASF SEC code of conduct.

Please note that the security email group is reserved for reporting undisclosed security vulnerabilities and following up on the vulnerability resolution process. Regular software Bug/Error reports should be directed to Github Issue/Discussion or the HugeGraph-Dev email group. Emails sent to the security list that are unrelated to security issues will be ignored.

The independent security email (group) address is: security@hugegraph.apache.org

The general process for handling security vulnerabilities is as follows:

• The reporter privately reports the vulnerability to the Apache HugeGraph SEC email group (including as much information as possible, such as reproducible versions, relevant descriptions, reproduction methods, and the scope of impact)
• The HugeGraph project security team collaborates privately with the reporter to discuss the vulnerability resolution (after preliminary confirmation, a CVE number can be requested for registration)
• The project creates a new version of the software package affected by the vulnerability to provide a fix
• At an appropriate time, a general description of the vulnerability and how to apply the fix will be publicly disclosed (in compliance with ASF standards, the announcement should not disclose sensitive information such as reproduction details)
• Official CVE release and related procedures follow the ASF-SEC page

Known Security Vulnerabilities (CVEs)

HugeGraph main project (Server/PD/Store)

• CVE-2024-27348: HugeGraph-Server - Command execution in gremlin
• CVE-2024-27349: HugeGraph-Server - Bypass whitelist in Auth mode
• CVE-2024-43441: HugeGraph-Server - Fixed JWT Token (Secret)
• CVE-2025-26866: HugeGraph-Server - RAFT and deserialization vulnerability

HugeGraph-Toolchain project (Hubble/Loader/Client/Tools/..)

• CVE-2024-27347: HugeGraph-Hubble - SSRF in Hubble connection page