From 11f33049c9abd1760135f3d49fbda1c64a0249e9 Mon Sep 17 00:00:00 2001 From: imbajin Date: Sat, 31 Jan 2026 21:22:19 +0800 Subject: [PATCH 1/5] doc: TOC, Quick Start, Architecture Overhaul README to improve developer onboarding and documentation. Adds a Table of Contents, Quick Start (TL;DR + detailed Docker, binary, and build-from-source instructions), verification steps, and a Module Map. Expands Features into bullet points and introduces detailed Architecture sections including ASCII and Mermaid diagrams, a deployment comparison table, and module overview. Adds contributor guidance, community/contact info, and ecosystem links. Also updates .serena/project.yml to set project_name and include placeholders for base/default modes, included optional tools, and fixed_tools to enable per-project Serena configuration. --- .serena/project.yml | 23 ++- README.md | 392 ++++++++++++++++++++++++++++++++++++++------ 2 files changed, 360 insertions(+), 55 deletions(-) diff --git a/.serena/project.yml b/.serena/project.yml index 5db60ba6b9..16ccb11693 100644 --- a/.serena/project.yml +++ b/.serena/project.yml @@ -79,6 +79,27 @@ excluded_tools: [] # initial prompt for the project. It will always be given to the LLM upon activating the project # (contrary to the memories, which are loaded on demand). initial_prompt: "" - +# the name by which the project can be referenced within Serena project_name: "server" + +# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default) included_optional_tools: [] + +# list of mode names to that are always to be included in the set of active modes +# The full set of modes to be activated is base_modes + default_modes. +# If the setting is undefined, the base_modes from the global configuration (serena_config.yml) apply. +# Otherwise, this setting overrides the global configuration. +# Set this to [] to disable base modes for this project. +# Set this to a list of mode names to always include the respective modes for this project. +base_modes: + +# list of mode names that are to be activated by default. +# The full set of modes to be activated is base_modes + default_modes. +# If the setting is undefined, the default_modes from the global configuration (serena_config.yml) apply. +# Otherwise, this overrides the setting from the global configuration (serena_config.yml). +# This setting can, in turn, be overridden by CLI parameters (--mode). +default_modes: + +# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools. +# This cannot be combined with non-empty excluded_tools or included_optional_tools. +fixed_tools: [] diff --git a/README.md b/README.md index f591f51ded..4b1dff70c9 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,32 @@ +--- + +**Quick Navigation:** [Architecture](#architecture) • [Quick Start](#quick-start) • [Module Map](#module-map) • [Ecosystem](#ecosystem) • [For Contributors](#for-contributors) • [Community](#community) + +--- + +## Table of Contents + +- [What is Apache HugeGraph?](#what-is-apache-hugegraph) +- [Features](#features) +- [Architecture](#architecture) +- [Quick Start](#quick-start) + - [TL;DR - 5 Minutes Quick Start](#tldr---5-minutes-quick-start) + - [Prerequisites](#prerequisites) + - [Option 1: Docker (Fastest)](#option-1-docker-fastest) + - [Option 2: Download Binary Package](#option-2-download-binary-package) + - [Option 3: Build from Source](#option-3-build-from-source) + - [Verify Installation](#verify-installation) +- [Module Map](#module-map) +- [Ecosystem](#ecosystem) +- [For Contributors](#for-contributors) +- [Contributing](#contributing) +- [License](#license) +- [Community](#community) +- [Thanks](#thanks) + ## What is Apache HugeGraph? [HugeGraph](https://hugegraph.apache.org/) is a fast and highly-scalable [graph database](https://en.wikipedia.org/wiki/Graph_database). @@ -23,96 +49,354 @@ achieved through the powerful [Gremlin](https://tinkerpop.apache.org/gremlin.htm ## Features -- Compliant to [Apache TinkerPop 3](https://tinkerpop.apache.org/), supports [Gremlin](https://tinkerpop.apache.org/gremlin.html) & [Cypher](https://en.wikipedia.org/wiki/Cypher_(query_language)) language -- Schema Metadata Management, including VertexLabel, EdgeLabel, PropertyKey and IndexLabel -- Multi-type Indexes, supporting exact query, range query and complex conditions combination query -- Plug-in Backend Store Framework, mainly support `RocksDB`/`HStore` + `HBase` for now and you could choose other backends in the [legacy version](https://hugegraph.apache.org/docs/download/download/) ≤ `1.5.0` (like `MySQL/PG`/`Cassandra` ...) -- Integration with `Flink/Spark/HDFS`, and friendly to connect other big data platforms -- Complete graph ecosystem (including both in/out-memory `Graph Computing` + `Graph Visualization & Tools` + `Graph Learning & AI`, see [here](#3-build-from-source)) +- **Compliant to [Apache TinkerPop 3](https://tinkerpop.apache.org/)**: Supports [Gremlin](https://tinkerpop.apache.org/gremlin.html) & [Cypher](https://en.wikipedia.org/wiki/Cypher_(query_language)) query languages +- **Schema Metadata Management**: VertexLabel, EdgeLabel, PropertyKey, and IndexLabel +- **Multi-type Indexes**: Exact query, range query, and complex conditions combination query +- **Plug-in Backend Store Framework**: Mainly supports `RocksDB`/`HStore` + `HBase`; other backends available in [legacy versions](https://hugegraph.apache.org/docs/download/download/) ≤ `1.5.0` (MySQL/PostgreSQL/Cassandra...) +- **Big Data Integration**: Seamless integration with `Flink`/`Spark`/`HDFS` +- **Complete Graph Ecosystem**: In/out-memory Graph Computing + Graph Visualization & Tools + Graph Learning & AI ## Architecture HugeGraph supports both **standalone** and **distributed** deployments: -| Module | Description | -|----------------------------------------|-----------------------------------------------------------------------------------------------------------| -| [hugegraph-server](hugegraph-server) | Core graph engine with REST API, Gremlin/Cypher support, and pluggable backends (RocksDB default) | -| [hugegraph-pd](hugegraph-pd) | Placement Driver for distributed mode - handles meta storage, partition management and cluster scheduling | -| [hugegraph-store](hugegraph-store) | Distributed storage with Raft consensus for high availability and horizontal scaling | -| [hugegraph-commons](hugegraph-commons) | Shared utilities, RPC framework and common components | +``` + ┌─────────────────────────────────────────────────────┐ + │ Client Layer │ + │ Gremlin Console │ REST API │ Cypher │ SDK/Tools │ + └─────────────────────────┬───────────────────────────┘ + │ + ┌─────────────────────────▼───────────────────────────┐ + │ HugeGraph Server (:8080) │ + │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ + │ │ REST API │ │ Gremlin │ │ Cypher Engine │ │ + │ │(Jersey 3)│ │ (TP 3.5) │ │ (OpenCypher) │ │ + │ └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │ + │ └─────────────┼─────────────────┘ │ + │ ┌───────▼───────┐ │ + │ │ Graph Engine │ │ + │ │(hugegraph-core)│ │ + │ └───────┬───────┘ │ + └─────────────────────┼───────────────────────────────┘ + │ + ┌────────────────────────────────┼────────────────────────────────┐ + │ │ │ +┌─────────────▼─────────────┐ ┌──────────────▼──────────────┐ ┌────────────▼────────────┐ +│ Standalone Mode │ │ Distributed Mode │ │ Legacy Backends │ +│ ┌─────────────────────┐ │ │ ┌───────────────────────┐ │ │ (≤ v1.5.0) │ +│ │ RocksDB │ │ │ │ HugeGraph-PD │ │ │ MySQL │ PostgreSQL │ +│ │ (embedded) │ │ │ │ (Raft, 3-5 nodes) │ │ │ Cassandra │ HBase │ +│ └─────────────────────┘ │ │ │ :8620/:8686 │ │ │ │ +│ │ │ └───────────┬───────────┘ │ └─────────────────────────┘ +│ Use Case: │ │ │ │ +│ Development/Testing │ │ ┌───────────▼───────────┐ │ +│ Single Node │ │ │ HugeGraph-Store │ │ +│ │ │ │ (Raft + RocksDB) │ │ +│ Data Scale: < 100GB │ │ │ (3+ nodes) :8520 │ │ +└───────────────────────────┘ │ └───────────────────────┘ │ + │ │ + │ Use Case: │ + │ Production/HA/Cluster │ + │ │ + │ Data Scale: 100GB+ │ + └─────────────────────────────┘ +``` + +### Deployment Mode Comparison + +| Mode | Components | Use Case | Data Scale | High Availability | +|------|------------|----------|------------|-------------------| +| **Standalone** | Server + RocksDB | Development, Testing, Single Node | < 100GB | No | +| **Distributed** | Server + PD (3-5 nodes) + Store (3+ nodes) | Production, HA, Horizontal Scaling | 100GB+ | Yes | + +### Module Overview + +| Module | Description | +|--------|-------------| +| [hugegraph-server](hugegraph-server) | Core graph engine with REST API, Gremlin/Cypher support, and pluggable backends (RocksDB default) | +| [hugegraph-pd](hugegraph-pd) | Placement Driver for distributed mode - handles meta storage, partition management and cluster scheduling | +| [hugegraph-store](hugegraph-store) | Distributed storage with Raft consensus for high availability and horizontal scaling | +| [hugegraph-commons](hugegraph-commons) | Shared utilities, RPC framework and common components | + +
+📊 Click to view detailed architecture diagram (Mermaid) + +```mermaid +flowchart TB + subgraph Clients["Client Layer"] + GC[Gremlin Console] + REST[REST Client] + CYPHER[Cypher Client] + SDK[SDK/Tools] + end + + subgraph Server["HugeGraph Server :8080"] + API[REST API
Jersey 3] + GS[Gremlin Server
TinkerPop 3.5] + CS[Cypher Engine
OpenCypher] + CORE[Graph Engine
hugegraph-core] + + API --> CORE + GS --> CORE + CS --> CORE + end + + subgraph Storage["Storage Layer"] + subgraph Standalone["Standalone Mode"] + ROCKS[(RocksDB
Embedded)] + end + + subgraph Distributed["Distributed Mode"] + PD[HugeGraph-PD
Raft Cluster
:8620/:8686] + STORE[HugeGraph-Store
Raft + RocksDB
:8520] + PD <--> STORE + end + + subgraph Legacy["Legacy Backends ≤v1.5.0"] + MYSQL[(MySQL)] + PG[(PostgreSQL)] + CASS[(Cassandra)] + HBASE[(HBase)] + end + end + + Clients --> Server + CORE --> ROCKS + CORE --> PD + CORE -.-> Legacy + + style Server fill:#e1f5ff + style Distributed fill:#fff4e1 + style Standalone fill:#f0f0f0 +``` -- **Standalone**: HugeGraph Server + RocksDB (for all-in-one deployment) -- **Distributed**: HugeGraph Server + PD + Store (Raft + RocksDB by default) +
## Quick Start -### 1. Docker (For Test) +### TL;DR - 5 Minutes Quick Start + +```bash +# Start HugeGraph with Docker +docker run -itd --name=hugegraph -p 8080:8080 hugegraph/hugegraph:1.7.0 -Use Docker to quickly start a HugeGraph server with `RocksDB` (in the background) for **testing or development**: +# Verify server is running +curl http://localhost:8080/apis/version +# Try a Gremlin query +curl -X POST http://localhost:8080/gremlin \ + -H "Content-Type: application/json" \ + -d '{"gremlin":"g.V().limit(5)"}' ``` -# (Optional) -# - add "-e PRELOAD=true" to auto-load a sample graph -docker run -itd --name=graph -e PASSWORD=xxx -p 8080:8080 hugegraph/hugegraph:1.7.0 + +> **Production Note**: For production environments or public network exposure, you **must** enable the [AuthSystem](https://hugegraph.apache.org/docs/config/config-authentication/) for security. + +### Prerequisites + +- **Java 11+** (required) +- **Maven 3.5+** (for building from source) + +Verify your environment: +```bash +java -version # Should show Java 11 or higher +mvn -version # Should show Maven 3.5+ ``` -Please visit [doc page](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/#3-deploy) or -the [README](hugegraph-server/hugegraph-dist/docker/README.md) for more details. ([Docker Compose](./hugegraph-server/hugegraph-dist/docker/example)) +### Option 1: Docker (Fastest) + +Docker is the quickest way to get started for **testing or development**: + +```bash +# Basic usage +docker run -itd --name=hugegraph -p 8080:8080 hugegraph/hugegraph:1.7.0 + +# With sample graph preloaded +docker run -itd --name=hugegraph -e PRELOAD=true -p 8080:8080 hugegraph/hugegraph:1.7.0 + +# With authentication enabled +docker run -itd --name=hugegraph -e PASSWORD=your_password -p 8080:8080 hugegraph/hugegraph:1.7.0 +``` -> Note: -> 1. The Docker image of HugeGraph is a convenience release, but not **official distribution** artifacts. You can find more details from [ASF Release Distribution Policy](https://infra.apache.org/release-distribution.html#dockerhub). -> 2. Recommend to use `release tag` (like `1.7.0`/`1.x.0`) for the stable version. Use `latest` tag to experience the newest functions in development. +For advanced Docker configurations, see: +- [Docker Documentation](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/#3-deploy) +- [Docker Compose Example](./hugegraph-server/hugegraph-dist/docker/example) +- [Docker README](hugegraph-server/hugegraph-dist/docker/README.md) -### 2. Download +> **Note**: Docker images are convenience releases, not **official ASF distribution artifacts**. See [ASF Release Distribution Policy](https://infra.apache.org/release-distribution.html#dockerhub) for details. +> +> **Version Tags**: Use release tags (`1.7.0`, `1.x.0`) for stable versions. Use `latest` for development features. -Visit [Download Page](https://hugegraph.apache.org/docs/download/download/) and refer the [doc](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/#32-download-the-binary-tar-tarball) -to download the latest release package and start the server. +### Option 2: Download Binary Package + +Download pre-built packages from the [Download Page](https://hugegraph.apache.org/docs/download/download/): + +```bash +# Download and extract +wget https://downloads.apache.org/incubator/hugegraph/{version}/apache-hugegraph-incubating-{version}.tar.gz +tar -xzf apache-hugegraph-incubating-{version}.tar.gz +cd apache-hugegraph-incubating-{version} + +# Initialize backend storage +bin/init-store.sh + +# Start server +bin/start-hugegraph.sh + +# Check server status +bin/monitor-hugegraph.sh +``` + +For detailed instructions, see the [Binary Installation Guide](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/#32-download-the-binary-tar-tarball). + +### Option 3: Build from Source + +Build from source for development or customization: + +```bash +# Clone repository +git clone https://github.com/apache/hugegraph.git +cd hugegraph + +# Build all modules (skip tests for faster build) +mvn clean package -DskipTests + +# Extract built package +cd install-dist/target +tar -xzf hugegraph-{version}.tar.gz +cd hugegraph-{version} + +# Initialize and start +bin/init-store.sh +bin/start-hugegraph.sh +``` -**Note:** if you want to use it in the production environment or expose it to the public network, you must enable the [AuthSystem](https://hugegraph.apache.org/docs/config/config-authentication/) to ensure safety. +For detailed build instructions, see [BUILDING.md](BUILDING.md) and [Build from Source Guide](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/#33-source-code-compilation). -### 3. Build From Source +### Verify Installation -Visit [Build From Source Page](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/#33-source-code-compilation) and follow the -steps to build the source code and start the server. +Once the server is running, verify the installation: -The project [doc page](https://hugegraph.apache.org/docs/) contains more information on HugeGraph -and provides detailed documentation for users. (Structure / Usage / API / Configs...) +```bash +# Check server version +curl http://localhost:8080/apis/version + +# Expected output: +# { +# "version": "1.7.0", +# "core": "1.7.0", +# "gremlin": "3.5.1", +# "api": "1.7.0" +# } + +# Try Gremlin console (if installed locally) +bin/gremlin-console.sh + +# In Gremlin console: +gremlin> :remote connect tinkerpop.server conf/remote.yaml +gremlin> :> g.V().limit(5) +``` + +For comprehensive documentation, visit the [HugeGraph Documentation](https://hugegraph.apache.org/docs/). + +## Module Map + +**Developer Navigation**: Find the right module for your task + +| I want to... | Module | Key Path | +|--------------|--------|----------| +| Understand graph operations | `hugegraph-core` | `StandardHugeGraph.java` | +| Modify REST APIs | `hugegraph-api` | `src/.../api/` | +| Add storage backend | `hugegraph-core` | `BackendStore.java` | +| Develop Gremlin features | `hugegraph-core` | `src/.../traversal/` | +| Develop Cypher features | `hugegraph-api` | `src/.../opencypher/` | +| Work on distributed coordination | `hugegraph-pd` | `hg-pd-core/` | +| Work on distributed storage | `hugegraph-store` | `hg-store-core/` | +| Add backend implementations | `hugegraph-server/hugegraph-{backend}` | `hugegraph-rocksdb/`, `hugegraph-hstore/` | +| Understand configuration | `hugegraph-dist` | `src/assembly/static/conf/` | +| Run tests | `hugegraph-test` | Test suites with multiple profiles | + +For detailed architecture and development guidance, see [AGENTS.md](AGENTS.md). ## Ecosystem -Other **HugeGraph** components/repositories: +Complete **HugeGraph** ecosystem components: -1. [hugegraph-toolchain](https://github.com/apache/hugegraph-toolchain) (graph tools **[loader](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-loader)/[dashboard](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-hubble)/[tool](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-tools)/[client](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-client)**) -2. [hugegraph-computer](https://github.com/apache/hugegraph-computer) (integrated **graph computing** system) -3. [hugegraph-ai](https://github.com/apache/incubator-hugegraph-ai) (integrated **Graph AI/LLM/KG** system) -4. [hugegraph-website](https://github.com/apache/hugegraph-doc) (**doc & website** code) +1. **[hugegraph-toolchain](https://github.com/apache/hugegraph-toolchain)** - Graph tools suite + - [Loader](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-loader) - Data import tool + - [Dashboard](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-hubble) - Web visualization platform + - [Tool](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-tools) - Command-line utilities + - [Client](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-client) - Java/Python client SDK -## License +2. **[hugegraph-computer](https://github.com/apache/hugegraph-computer)** - Integrated **graph computing** system -HugeGraph is licensed under [Apache 2.0 License](LICENSE). +3. **[hugegraph-ai](https://github.com/apache/incubator-hugegraph-ai)** - **Graph AI/LLM/Knowledge Graph** integration + +4. **[hugegraph-website](https://github.com/apache/hugegraph-doc)** - **Documentation & website** repository + +## For Contributors + +**New to HugeGraph?** Follow this path to get started: + +1. **📖 Understand the Architecture** + - Read [AGENTS.md](AGENTS.md) for detailed module structure and development patterns + - Review the [Architecture Diagram](#architecture) above + +2. **🛠️ Set Up Your Environment** + - Install Java 11+ and Maven 3.5+ + - Follow [BUILDING.md](BUILDING.md) for build instructions + - Import `hugegraph-style.xml` into your IDE for code style + +3. **🔍 Find Your First Issue** + - Browse [Good First Issues](https://github.com/apache/hugegraph/issues?q=label%3A%22good+first+issue%22) + - Check [Help Wanted Issues](https://github.com/apache/hugegraph/issues?q=label%3A%22help+wanted%22) + +4. **💡 Learn the Codebase** + - Use the [Module Map](#module-map) to navigate + - Run tests to understand behavior: `mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,memory` + - Try modifying a test and see what breaks + +5. **✅ Code Standards** + - Line length: 100 characters + - Indentation: 4 spaces + - No star imports + - Commit format: `feat|fix|refactor(module): description` + +6. **🚀 Submit Your Contribution** + - Read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines + - Follow the [Contribution Guidelines](https://hugegraph.apache.org/docs/contribution-guidelines/) + - Use [GitHub Desktop](https://desktop.github.com/) to simplify the PR process ## Contributing -- Welcome to contribute to HugeGraph, please see [`How to Contribute`](CONTRIBUTING.md) & [Guidelines](https://hugegraph.apache.org/docs/contribution-guidelines/) for more information. -- Note: It's recommended to use [GitHub Desktop](https://desktop.github.com/) to greatly simplify the PR and commit process. -- Thank you to all the people who already contributed to HugeGraph! +Welcome to contribute to HugeGraph! + +- **How to Contribute**: See [CONTRIBUTING.md](CONTRIBUTING.md) and [Contribution Guidelines](https://hugegraph.apache.org/docs/contribution-guidelines/) +- **Code Style**: Import `hugegraph-style.xml` into your IDE +- **PR Tool**: [GitHub Desktop](https://desktop.github.com/) is recommended for simpler workflow + +Thank you to all the contributors who have helped make HugeGraph better! [![contributors graph](https://contrib.rocks/image?repo=apache/hugegraph)](https://github.com/apache/incubator-hugegraph/graphs/contributors) -## Thanks +## License -HugeGraph relies on the [TinkerPop](http://tinkerpop.apache.org) framework, we refer to the storage structure of Titan and the schema definition of DataStax. -Thanks to TinkerPop, thanks to Titan, thanks to DataStax. Thanks to all other organizations or authors who contributed to the project. +HugeGraph is licensed under [Apache 2.0 License](LICENSE). -You are welcome to contribute to HugeGraph, -and we are looking forward to working with you to build an excellent open-source community. +## Community -## Contact Us +**Get Help & Stay Connected** -- [GitHub Issues](https://github.com/apache/hugegraph/issues): Feedback on usage issues and functional requirements (quick response) -- Feedback Email: [dev@hugegraph.apache.org](mailto:dev@hugegraph.apache.org) ([subscriber](https://hugegraph.apache.org/docs/contribution-guidelines/subscribe/) only) -- Slack: [ASF Online Channel](https://the-asf.slack.com/archives/C059UU2FJ23) -- WeChat public account: Apache HugeGraph, welcome to scan this QR code to follow us. +- **[GitHub Issues](https://github.com/apache/hugegraph/issues)**: Report bugs and request features (quick response) +- **Mailing List**: [dev@hugegraph.apache.org](mailto:dev@hugegraph.apache.org) ([subscribe here](https://hugegraph.apache.org/docs/contribution-guidelines/subscribe/)) +- **Slack**: [ASF HugeGraph Channel](https://the-asf.slack.com/archives/C059UU2FJ23) +- **WeChat**: Scan the QR code to follow Apache HugeGraph official account + +

+WeChat QR Code +

+ +## Thanks - QR png +HugeGraph relies on the [Apache TinkerPop](http://tinkerpop.apache.org) framework. We are grateful to the TinkerPop community, Titan, and DataStax for their foundational work. Thanks to all contributors and organizations who have helped make HugeGraph possible. +You are welcome to contribute to HugeGraph, and we look forward to working with you to build an excellent open-source community. From e8f5e8cd66c6ea7b2c3f1c45166cecbe53289145 Mon Sep 17 00:00:00 2001 From: imbajin Date: Sat, 31 Jan 2026 21:46:53 +0800 Subject: [PATCH 2/5] Update README.md --- README.md | 108 ++++++++++++++++++++++++------------------------------ 1 file changed, 48 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 4b1dff70c9..b1bf066668 100644 --- a/README.md +++ b/README.md @@ -20,26 +20,6 @@ --- -## Table of Contents - -- [What is Apache HugeGraph?](#what-is-apache-hugegraph) -- [Features](#features) -- [Architecture](#architecture) -- [Quick Start](#quick-start) - - [TL;DR - 5 Minutes Quick Start](#tldr---5-minutes-quick-start) - - [Prerequisites](#prerequisites) - - [Option 1: Docker (Fastest)](#option-1-docker-fastest) - - [Option 2: Download Binary Package](#option-2-download-binary-package) - - [Option 3: Build from Source](#option-3-build-from-source) - - [Verify Installation](#verify-installation) -- [Module Map](#module-map) -- [Ecosystem](#ecosystem) -- [For Contributors](#for-contributors) -- [Contributing](#contributing) -- [License](#license) -- [Community](#community) -- [Thanks](#thanks) - ## What is Apache HugeGraph? [HugeGraph](https://hugegraph.apache.org/) is a fast and highly-scalable [graph database](https://en.wikipedia.org/wiki/Graph_database). @@ -49,12 +29,28 @@ achieved through the powerful [Gremlin](https://tinkerpop.apache.org/gremlin.htm ## Features -- **Compliant to [Apache TinkerPop 3](https://tinkerpop.apache.org/)**: Supports [Gremlin](https://tinkerpop.apache.org/gremlin.html) & [Cypher](https://en.wikipedia.org/wiki/Cypher_(query_language)) query languages - **Schema Metadata Management**: VertexLabel, EdgeLabel, PropertyKey, and IndexLabel - **Multi-type Indexes**: Exact query, range query, and complex conditions combination query - **Plug-in Backend Store Framework**: Mainly supports `RocksDB`/`HStore` + `HBase`; other backends available in [legacy versions](https://hugegraph.apache.org/docs/download/download/) ≤ `1.5.0` (MySQL/PostgreSQL/Cassandra...) - **Big Data Integration**: Seamless integration with `Flink`/`Spark`/`HDFS` - **Complete Graph Ecosystem**: In/out-memory Graph Computing + Graph Visualization & Tools + Graph Learning & AI +- **Dual Query Language Support**: [Gremlin](https://tinkerpop.apache.org/gremlin.html) (via [Apache TinkerPop 3](https://tinkerpop.apache.org/)) and [Cypher](https://en.wikipedia.org/wiki/Cypher_(query_language)) (OpenCypher) + +## Ecosystem + +Complete **HugeGraph** ecosystem components: + +1. **[hugegraph-toolchain](https://github.com/apache/hugegraph-toolchain)** - Graph tools suite + - [Loader](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-loader) - Data import tool + - [Dashboard](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-hubble) - Web visualization platform + - [Tool](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-tools) - Command-line utilities + - [Client](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-client) - Java/Python client SDK + +2. **[hugegraph-computer](https://github.com/apache/hugegraph-computer)** - Integrated **graph computing** system + +3. **[hugegraph-ai](https://github.com/apache/incubator-hugegraph-ai)** - **Graph AI/LLM/Knowledge Graph** integration + +4. **[hugegraph-website](https://github.com/apache/hugegraph-doc)** - **Documentation & website** repository ## Architecture @@ -83,16 +79,17 @@ HugeGraph supports both **standalone** and **distributed** deployments: │ │ │ ┌─────────────▼─────────────┐ ┌──────────────▼──────────────┐ ┌────────────▼────────────┐ │ Standalone Mode │ │ Distributed Mode │ │ Legacy Backends │ -│ ┌─────────────────────┐ │ │ ┌───────────────────────┐ │ │ (≤ v1.5.0) │ +│ ┌─────────────────────┐ │ │ ┌───────────────────────┐ │ │ (≤v1.5) │ │ │ RocksDB │ │ │ │ HugeGraph-PD │ │ │ MySQL │ PostgreSQL │ -│ │ (embedded) │ │ │ │ (Raft, 3-5 nodes) │ │ │ Cassandra │ HBase │ +│ │ (embedded) │ │ │ │ (Raft, 3-5 nodes) │ │ │ Cassandra │ +│ └─────────────────────┘ │ │ │ :8620/:8686 │ │ │ HBase (≤v1.7) │ │ └─────────────────────┘ │ │ │ :8620/:8686 │ │ │ │ │ │ │ └───────────┬───────────┘ │ └─────────────────────────┘ │ Use Case: │ │ │ │ │ Development/Testing │ │ ┌───────────▼───────────┐ │ │ Single Node │ │ │ HugeGraph-Store │ │ │ │ │ │ (Raft + RocksDB) │ │ -│ Data Scale: < 100GB │ │ │ (3+ nodes) :8520 │ │ +│ Data Scale: < 1TB │ │ │ (3+ nodes) :8520 │ │ └───────────────────────────┘ │ └───────────────────────┘ │ │ │ │ Use Case: │ @@ -106,7 +103,7 @@ HugeGraph supports both **standalone** and **distributed** deployments: | Mode | Components | Use Case | Data Scale | High Availability | |------|------------|----------|------------|-------------------| -| **Standalone** | Server + RocksDB | Development, Testing, Single Node | < 100GB | No | +| **Standalone** | Server + RocksDB | Development, Testing, Single Node | < 1TB | Basic | | **Distributed** | Server + PD (3-5 nodes) + Store (3+ nodes) | Production, HA, Horizontal Scaling | 100GB+ | Yes | ### Module Overview @@ -152,11 +149,11 @@ flowchart TB PD <--> STORE end - subgraph Legacy["Legacy Backends ≤v1.5.0"] + subgraph Legacy["Legacy Backends (≤v1.5)"] MYSQL[(MySQL)] PG[(PostgreSQL)] CASS[(Cassandra)] - HBASE[(HBase)] + HBASE[(HBase, ≤v1.7)] end end @@ -174,7 +171,7 @@ flowchart TB ## Quick Start -### TL;DR - 5 Minutes Quick Start +### 5 Minutes Quick Start ```bash # Start HugeGraph with Docker @@ -196,12 +193,6 @@ curl -X POST http://localhost:8080/gremlin \ - **Java 11+** (required) - **Maven 3.5+** (for building from source) -Verify your environment: -```bash -java -version # Should show Java 11 or higher -mvn -version # Should show Maven 3.5+ -``` - ### Option 1: Docker (Fastest) Docker is the quickest way to get started for **testing or development**: @@ -226,7 +217,8 @@ For advanced Docker configurations, see: > > **Version Tags**: Use release tags (`1.7.0`, `1.x.0`) for stable versions. Use `latest` for development features. -### Option 2: Download Binary Package +
+Option 2: Download Binary Package Download pre-built packages from the [Download Page](https://hugegraph.apache.org/docs/download/download/): @@ -248,7 +240,10 @@ bin/monitor-hugegraph.sh For detailed instructions, see the [Binary Installation Guide](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/#32-download-the-binary-tar-tarball). -### Option 3: Build from Source +
+ +
+Option 3: Build from Source Build from source for development or customization: @@ -272,7 +267,10 @@ bin/start-hugegraph.sh For detailed build instructions, see [BUILDING.md](BUILDING.md) and [Build from Source Guide](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/#33-source-code-compilation). -### Verify Installation +
+ +
+Verify Installation Once the server is running, verify the installation: @@ -298,6 +296,8 @@ gremlin> :> g.V().limit(5) For comprehensive documentation, visit the [HugeGraph Documentation](https://hugegraph.apache.org/docs/). +
+ ## Module Map **Developer Navigation**: Find the right module for your task @@ -317,55 +317,43 @@ For comprehensive documentation, visit the [HugeGraph Documentation](https://hug For detailed architecture and development guidance, see [AGENTS.md](AGENTS.md). -## Ecosystem - -Complete **HugeGraph** ecosystem components: - -1. **[hugegraph-toolchain](https://github.com/apache/hugegraph-toolchain)** - Graph tools suite - - [Loader](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-loader) - Data import tool - - [Dashboard](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-hubble) - Web visualization platform - - [Tool](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-tools) - Command-line utilities - - [Client](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-client) - Java/Python client SDK - -2. **[hugegraph-computer](https://github.com/apache/hugegraph-computer)** - Integrated **graph computing** system - -3. **[hugegraph-ai](https://github.com/apache/incubator-hugegraph-ai)** - **Graph AI/LLM/Knowledge Graph** integration - -4. **[hugegraph-website](https://github.com/apache/hugegraph-doc)** - **Documentation & website** repository - -## For Contributors +
+For Contributors **New to HugeGraph?** Follow this path to get started: -1. **📖 Understand the Architecture** +1. **Understand the Architecture** - Read [AGENTS.md](AGENTS.md) for detailed module structure and development patterns - Review the [Architecture Diagram](#architecture) above -2. **🛠️ Set Up Your Environment** +2. **Set Up Your Environment** - Install Java 11+ and Maven 3.5+ - Follow [BUILDING.md](BUILDING.md) for build instructions - Import `hugegraph-style.xml` into your IDE for code style -3. **🔍 Find Your First Issue** +3. **Find Your First Issue** - Browse [Good First Issues](https://github.com/apache/hugegraph/issues?q=label%3A%22good+first+issue%22) - Check [Help Wanted Issues](https://github.com/apache/hugegraph/issues?q=label%3A%22help+wanted%22) -4. **💡 Learn the Codebase** +4. **Learn the Codebase** - Use the [Module Map](#module-map) to navigate + - Try [DeepWiki](https://deepwiki.com/apache/hugegraph) for AI-powered codebase understanding - Run tests to understand behavior: `mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,memory` - Try modifying a test and see what breaks -5. **✅ Code Standards** +5. **Code Standards** - Line length: 100 characters - Indentation: 4 spaces - No star imports - Commit format: `feat|fix|refactor(module): description` -6. **🚀 Submit Your Contribution** +6. **Submit Your Contribution** - Read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines - Follow the [Contribution Guidelines](https://hugegraph.apache.org/docs/contribution-guidelines/) - Use [GitHub Desktop](https://desktop.github.com/) to simplify the PR process +
+ ## Contributing Welcome to contribute to HugeGraph! From ce10be23a9eeabdc4d8f8a686346eadc17eafa1d Mon Sep 17 00:00:00 2001 From: imbajin Date: Sat, 31 Jan 2026 22:00:09 +0800 Subject: [PATCH 3/5] Update README.md --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b1bf066668..c19924e787 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,6 @@ HugeGraph supports both **standalone** and **distributed** deployments: │ │ RocksDB │ │ │ │ HugeGraph-PD │ │ │ MySQL │ PostgreSQL │ │ │ (embedded) │ │ │ │ (Raft, 3-5 nodes) │ │ │ Cassandra │ │ └─────────────────────┘ │ │ │ :8620/:8686 │ │ │ HBase (≤v1.7) │ -│ └─────────────────────┘ │ │ │ :8620/:8686 │ │ │ │ │ │ │ └───────────┬───────────┘ │ └─────────────────────────┘ │ Use Case: │ │ │ │ │ Development/Testing │ │ ┌───────────▼───────────┐ │ @@ -329,7 +328,7 @@ For detailed architecture and development guidance, see [AGENTS.md](AGENTS.md). 2. **Set Up Your Environment** - Install Java 11+ and Maven 3.5+ - Follow [BUILDING.md](BUILDING.md) for build instructions - - Import `hugegraph-style.xml` into your IDE for code style + - Configure your IDE to use `.editorconfig` for code style and `style/checkstyle.xml` for Checkstyle rules 3. **Find Your First Issue** - Browse [Good First Issues](https://github.com/apache/hugegraph/issues?q=label%3A%22good+first+issue%22) @@ -359,7 +358,7 @@ For detailed architecture and development guidance, see [AGENTS.md](AGENTS.md). Welcome to contribute to HugeGraph! - **How to Contribute**: See [CONTRIBUTING.md](CONTRIBUTING.md) and [Contribution Guidelines](https://hugegraph.apache.org/docs/contribution-guidelines/) -- **Code Style**: Import `hugegraph-style.xml` into your IDE +- **Code Style**: Configure your IDE to use `.editorconfig` for code style and `style/checkstyle.xml` for Checkstyle rules - **PR Tool**: [GitHub Desktop](https://desktop.github.com/) is recommended for simpler workflow Thank you to all the contributors who have helped make HugeGraph better! From 332e4b02c65cf7f625eddd93c0d479d154c8c549 Mon Sep 17 00:00:00 2001 From: imbajin Date: Sat, 31 Jan 2026 22:04:12 +0800 Subject: [PATCH 4/5] Update README.md --- README.md | 78 +++++++++++++++++++++++++++---------------------------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index c19924e787..5391f9f45b 100644 --- a/README.md +++ b/README.md @@ -57,45 +57,45 @@ Complete **HugeGraph** ecosystem components: HugeGraph supports both **standalone** and **distributed** deployments: ``` - ┌─────────────────────────────────────────────────────┐ - │ Client Layer │ - │ Gremlin Console │ REST API │ Cypher │ SDK/Tools │ - └─────────────────────────┬───────────────────────────┘ - │ - ┌─────────────────────────▼───────────────────────────┐ - │ HugeGraph Server (:8080) │ - │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ - │ │ REST API │ │ Gremlin │ │ Cypher Engine │ │ - │ │(Jersey 3)│ │ (TP 3.5) │ │ (OpenCypher) │ │ - │ └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │ - │ └─────────────┼─────────────────┘ │ - │ ┌───────▼───────┐ │ - │ │ Graph Engine │ │ - │ │(hugegraph-core)│ │ - │ └───────┬───────┘ │ - └─────────────────────┼───────────────────────────────┘ - │ - ┌────────────────────────────────┼────────────────────────────────┐ - │ │ │ -┌─────────────▼─────────────┐ ┌──────────────▼──────────────┐ ┌────────────▼────────────┐ -│ Standalone Mode │ │ Distributed Mode │ │ Legacy Backends │ -│ ┌─────────────────────┐ │ │ ┌───────────────────────┐ │ │ (≤v1.5) │ -│ │ RocksDB │ │ │ │ HugeGraph-PD │ │ │ MySQL │ PostgreSQL │ -│ │ (embedded) │ │ │ │ (Raft, 3-5 nodes) │ │ │ Cassandra │ -│ └─────────────────────┘ │ │ │ :8620/:8686 │ │ │ HBase (≤v1.7) │ -│ │ │ └───────────┬───────────┘ │ └─────────────────────────┘ -│ Use Case: │ │ │ │ -│ Development/Testing │ │ ┌───────────▼───────────┐ │ -│ Single Node │ │ │ HugeGraph-Store │ │ -│ │ │ │ (Raft + RocksDB) │ │ -│ Data Scale: < 1TB │ │ │ (3+ nodes) :8520 │ │ -└───────────────────────────┘ │ └───────────────────────┘ │ - │ │ - │ Use Case: │ - │ Production/HA/Cluster │ - │ │ - │ Data Scale: 100GB+ │ - └─────────────────────────────┘ + ┌─────────────────────────────────────────────────────┐ + │ Client Layer │ + │ Gremlin Console │ REST API │ Cypher │ SDK/Tools │ + └─────────────────────────┬───────────────────────────┘ + │ + ┌─────────────────────────▼───────────────────────────┐ + │ HugeGraph Server (:8080) │ + │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ + │ │ REST API │ │ Gremlin │ │ Cypher Engine │ │ + │ │(Jersey 3)│ │ (TP 3.5) │ │ (OpenCypher) │ │ + │ └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │ + │ └─────────────┼─────────────────┘ │ + │ ┌────────▼────────┐ │ + │ │ Graph Engine │ │ + │ │(hugegraph-core) │ │ + │ └────────┬────────┘ │ + └─────────────────────┼───────────────────────────────┘ + │ + ┌────────────────────────────────┼────────────────────────────────┐ + │ │ │ +┌────────────▼────────────┐ ┌───────────────▼───────────────┐ ┌───────────▼──────────┐ +│ Standalone Mode │ │ Distributed Mode │ │ Legacy Backends │ +│ ┌───────────────────┐ │ │ ┌─────────────────────────┐ │ │ (≤v1.5) │ +│ │ RocksDB │ │ │ │ HugeGraph-PD │ │ │ MySQL │ PostgreSQL │ +│ │ (embedded) │ │ │ │ (Raft, 3-5 nodes) │ │ │ Cassandra │ +│ └───────────────────┘ │ │ │ :8620/:8686 │ │ │ HBase (≤v1.7) │ +│ │ │ └────────────┬────────────┘ │ └──────────────────────┘ +│ Use Case: │ │ │ │ +│ Development/Testing │ │ ┌────────────▼────────────┐ │ +│ Single Node │ │ │ HugeGraph-Store │ │ +│ │ │ │ (Raft + RocksDB) │ │ +│ Data Scale: < 1TB │ │ │ (3+ nodes) :8520 │ │ +└─────────────────────────┘ │ └─────────────────────────┘ │ + │ │ + │ Use Case: │ + │ Production/HA/Cluster │ + │ │ + │ Data Scale: 100GB+ │ + └───────────────────────────────┘ ``` ### Deployment Mode Comparison From 1fcfe538df5ac535f8e0fbf1b6697d3d4789042c Mon Sep 17 00:00:00 2001 From: imbajin Date: Mon, 2 Feb 2026 17:00:55 +0800 Subject: [PATCH 5/5] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5391f9f45b..c027cda43f 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,7 @@ HugeGraph supports both **standalone** and **distributed** deployments: │ Use Case: │ │ Production/HA/Cluster │ │ │ - │ Data Scale: 100GB+ │ + │ Data Scale: < 1000 TB │ └───────────────────────────────┘ ``` @@ -103,7 +103,7 @@ HugeGraph supports both **standalone** and **distributed** deployments: | Mode | Components | Use Case | Data Scale | High Availability | |------|------------|----------|------------|-------------------| | **Standalone** | Server + RocksDB | Development, Testing, Single Node | < 1TB | Basic | -| **Distributed** | Server + PD (3-5 nodes) + Store (3+ nodes) | Production, HA, Horizontal Scaling | 100GB+ | Yes | +| **Distributed** | Server + PD (3-5 nodes) + Store (3+ nodes) | Production, HA, Horizontal Scaling | < 1000 TB | Yes | ### Module Overview