imbajin commented on code in PR #900: URL: https://github.com/apache/hugegraph-toolchain/pull/900#discussion_r4505199224
########## README.md: ########## @@ -1,511 +1,138 @@ -# hugegraph-toolchain +# Apache HugeGraph Toolchain [](https://www.apache.org/licenses/LICENSE-2.0.html) -[](https://github.com/apache/hugegraph-toolchain/actions/workflows/client-ci.yml) -[](https://github.com/apache/hugegraph-toolchain/actions/workflows/loader-ci.yml) -[](https://github.com/apache/hugegraph-toolchain/actions/workflows/hubble-ci.yml) -[](https://github.com/apache/hugegraph-toolchain/actions/workflows/tools-ci.yml) +[](https://github.com/apache/hugegraph-toolchain/actions/workflows/client-ci.yml) +[](https://github.com/apache/hugegraph-toolchain/actions/workflows/loader-ci.yml) +[](https://github.com/apache/hugegraph-toolchain/actions/workflows/hubble-ci.yml) +[](https://github.com/apache/hugegraph-toolchain/actions/workflows/tools-ci.yml) [](https://mvnrepository.com/artifact/org.apache.hugegraph/hugegraph-toolchain) -[](https://deepwiki.com/apache/hugegraph-toolchain) -## What is HugeGraph Toolchain? +HugeGraph Toolchain is the client and operations suite for [Apache HugeGraph](https://github.com/apache/hugegraph). It provides application SDKs, bulk data loading, browser-based graph management, command-line utilities and Spark integration. -A comprehensive suite of client SDKs, data tools, and management utilities for [Apache HugeGraph](https://github.com/apache/hugegraph) graph database. Build applications, load data, and manage graphs with production-ready tools. +**Start here:** [Choose a tool](#choose-a-tool) · [Quick start](#quick-start) · [Modules](#modules) · [Documentation](#documentation) · [Development](#development) -Hubble's primary authentication and connection design targets HugeGraph `1.8/master`: PD discovery supplies the server address, anonymous mode uses a real unauthenticated client, and account/GraphSpace permissions are reduced to four readable presets. A thin adapter keeps 1.7 usable and limits 1.5 to its standalone core graph workflow; version checks are centralized rather than spread across UI pages. +## Choose a tool -### Hubble Workbench +| Goal | Component | Entry point | +|---|---|---| +| Build a Java application | [`hugegraph-client`](hugegraph-client/) | `HugeClient` SDK | +| Import CSV, JSON, JDBC, HDFS or Kafka data | [`hugegraph-loader`](hugegraph-loader/) | `hugegraph-loader.sh` | +| Explore graphs and manage schemas in a browser | [`hugegraph-hubble`](hugegraph-hubble/) | Hubble Web UI | +| Back up, restore, migrate or inspect graphs | [`hugegraph-tools`](hugegraph-tools/) | `bin/hugegraph` | +| Read or write HugeGraph from Spark | [`hugegraph-spark-connector`](hugegraph-spark-connector/) | Spark DataSource | +| Use a Go client | [`hugegraph-client-go`](hugegraph-client-go/) | Go package | +| Use Python | [HugeGraph Python client](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-python-client) | `pyhugegraph` | -Hubble brings graph exploration, schema preparation, asynchronous analysis, and distributed cluster operations into one workspace. +The Java client is the shared foundation for Loader, the Hubble backend, Tools and the Spark connector. The Hubble frontend communicates with its backend. A client contract change therefore requires validation of the affected downstream modules. - - -### Distributed Operations - -The cluster overview keeps service topology, node health, source status, and capacity facts in one operational view. - - - -**Quick Navigation**: [Architecture](#architecture-overview) | [Quick Start](#quick-start) | [Modules](#module-overview) | [Build](#build--development) | [Docker](#docker) | [Related Projects](#related-projects) - -## Related Projects - -**HugeGraph Ecosystem**: -1. [hugegraph](https://github.com/apache/hugegraph) - Core graph database (**[pd](https://github.com/apache/hugegraph/tree/master/hugegraph-pd)** / **[store](https://github.com/apache/hugegraph/tree/master/hugegraph-store)** / **[server](https://github.com/apache/hugegraph/tree/master/hugegraph-server)** / **[commons](https://github.com/apache/hugegraph/tree/master/hugegraph-commons)**) -2. [hugegraph-computer](https://github.com/apache/hugegraph-computer) - Distributed graph computing system -3. [hugegraph-ai](https://github.com/apache/hugegraph-ai) - Graph AI/LLM/Knowledge Graph integration -4. [hugegraph-website](https://github.com/apache/hugegraph-doc) - Documentation and website - -## Architecture Overview - -```mermaid -graph TB - subgraph server ["HugeGraph Server"] - SERVER[("Graph Database")] - end - - subgraph distributed ["Distributed Mode (Optional)"] - PD["hugegraph-pd<br/>(Placement Driver)"] - STORE["hugegraph-store<br/>(Storage Nodes)"] - end - - subgraph clients ["Client SDKs"] - CLIENT["hugegraph-client<br/>(Java)"] - end - - subgraph data ["Data Tools"] - LOADER["hugegraph-loader<br/>(Batch Import)"] - SPARK["hugegraph-spark-connector<br/>(Spark I/O)"] - end - - subgraph mgmt ["Management Tools"] - HUBBLE["hugegraph-hubble<br/>(Web UI)"] - TOOLS["hugegraph-tools<br/>(CLI)"] - end - - SERVER <-->|REST API| CLIENT - PD -.->|coordinates| STORE - SERVER -.->|distributed backend| PD - - CLIENT --> LOADER - CLIENT --> HUBBLE - CLIENT --> TOOLS - CLIENT --> SPARK - HUBBLE -.->|PD discovery UI| PD - - LOADER -.->|Sources| SRC["CSV | JSON | HDFS<br/>MySQL | Kafka"] - SPARK -.->|I/O| SPK["Spark DataFrames"] - - style distributed stroke-dasharray: 5 5 -``` - -<details> -<summary>ASCII diagram (for terminals/editors)</summary> - -``` - ┌─────────────────────────┐ - │ HugeGraph Server │ - │ (Graph Database) │ - └───────────┬─────────────┘ - │ REST API - ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┼ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐ - Distributed (Optional)│ - │ ┌───────────┐ │ ┌───────────┐ │ - │hugegraph- │◄──────┴──────►│hugegraph- │ - │ │ pd │ │ store │ │ - └───────────┘ └───────────┘ - └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘ - │ - ┌─────────────────────┼─────────────────────┐ - │ │ │ - ▼ ▼ ▼ - ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ - │ hugegraph- │ │ Other Client │ │ Other REST │ - │ client (Java) │ │ SDKs (Go/Py) │ │ Clients │ - └───────┬────────┘ └────────────────┘ └────────────────┘ - │ depends on - ┌───────┼───────────┬───────────────────┐ - │ │ │ │ - ▼ ▼ ▼ ▼ -┌────────┐ ┌────────┐ ┌──────────┐ ┌───────────────────┐ -│ loader │ │ hubble │ │ tools │ │ spark-connector │ -│ (ETL) │ │ (Web) │ │ (CLI) │ │ (Spark I/O) │ -└────────┘ └────────┘ └──────────┘ └───────────────────┘ -``` -</details> - -## Quick Start - -### Prerequisites - -| Requirement | Version | Notes | -|-------------|---------|-------| -| JDK | 17+ | Build and run the core tools with Java 17 | -| Maven | 3.6.3+ | For building from source | -| HugeGraph Server | Current 1.8 or official 1.7.0 | See the migration guide for Server 1.5 scope | - -For the Java 17 candidate SDK, upgrade procedure and compatibility boundary, see [the migration guide](docs/java17-migration.md). - -### Choose Your Path - -| I want to... | Use This | Get Started | -|--------------|----------|-------------| -| Visualize graphs via Web UI | Hubble | Docker: `docker run -p 8088:8088 hugegraph/hugegraph-hubble` | -| Load CSV/JSON data into graph | Loader | CLI with JSON mapping config ([docs](https://hugegraph.apache.org/docs/quickstart/hugegraph-loader/)) | -| Build a Java app with HugeGraph | Client | Maven dependency ([example](#hugegraph-client)) | -| Backup/restore graphs | Tools | CLI commands ([docs](https://hugegraph.apache.org/docs/quickstart/hugegraph-tools/)) | -| Process graphs with Spark | Spark Connector | DataFrame API ([module](#hugegraph-spark-connector)) | - -### Docker Quick Start - -```bash -# Hubble Web UI (port 8088) -docker run -d -p 8088:8088 --name hubble hugegraph/hugegraph-hubble - -# Loader (batch data import) -docker run --rm hugegraph/hugegraph-loader ./bin/hugegraph-loader.sh -f example.json -``` - -## Module Overview - -Before committing a new source or test file, run the same license-header check -used by CI (`license-eye` from `apache/skywalking-eyes` is required): - -```bash -./tools/check-license-header.sh -``` - -Do not use shortened Apache headers: the complete header configured in -`.licenserc.yaml` is required. - -### hugegraph-client - -**Purpose**: Official Java SDK for HugeGraph Server - -**Key Features**: -- Schema management (PropertyKey, VertexLabel, EdgeLabel, IndexLabel) -- Graph operations (CRUD vertices/edges) -- Gremlin query execution -- Built-in traversers (shortest path, k-neighbor, k-out, paths, etc.) -- Multi-graph and authentication support - -**Entry Point**: `org.apache.hugegraph.driver.HugeClient` - -**Quick Example**: -```java -HugeClient client = HugeClient.builder("http://localhost:8080";, "hugegraph").build(); - -// Schema management -client.schema().propertyKey("name").asText().ifNotExist().create(); -client.schema().vertexLabel("person") - .properties("name") - .ifNotExist() - .create(); - -// Graph operations -Vertex vertex = client.graph().addVertex(T.label, "person", "name", "Alice"); -``` - -📖 [Documentation](https://hugegraph.apache.org/docs/quickstart/hugegraph-client/) | 📁 [Source](./hugegraph-client) - ---- - -### Other Client SDKs - -<details> -<summary><b>hugegraph-client-go</b> (Go SDK - WIP)</summary> - -**Purpose**: Official Go SDK for HugeGraph Server - -**Key Features**: -- RESTful API client for HugeGraph -- Schema and graph operations -- Gremlin query support -- Idiomatic Go interface - -**Entry Point**: `github.com/apache/hugegraph-toolchain/hugegraph-client-go` - -**Quick Example**: -```go -import "github.com/apache/hugegraph-toolchain/hugegraph-client-go" - -client := hugegraph.NewClient("http://localhost:8080";, "hugegraph") -// Schema and graph operations -``` - -📁 [Source](./hugegraph-client-go) - -</details> - -> **Looking for other languages?** See [hugegraph-python-client](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-python-client) in the hugegraph-ai repository. - ---- - -### hugegraph-loader - -**Purpose**: Batch data import tool from multiple data sources - -**Key Features**: -- **Sources**: CSV, JSON, HDFS, MySQL, Kafka, existing HugeGraph -- JSON-based mapping configuration -- Parallel loading with configurable threads -- Error handling and retry mechanisms -- Progress tracking and logging - -**Entry Point**: `bin/hugegraph-loader.sh` - -**Quick Example**: -```bash -# Load data from CSV -./bin/hugegraph-loader.sh -f mapping.json -g hugegraph - -# Example mapping.json structure -{ - "vertices": [ - { - "label": "person", - "input": { "type": "file", "path": "persons.csv" }, - "mapping": { "name": "name", "age": "age" } - } - ] -} +```text +HugeGraph Server + ▲ + │ REST APIs + │ +HugeGraph Java Client + ├─ Loader + ├─ Hubble backend ◀─ HTTP ── Hubble frontend + ├─ Tools + └─ Spark Connector ``` -📖 [Documentation](https://hugegraph.apache.org/docs/quickstart/hugegraph-loader/) | 📁 [Source](./hugegraph-loader) - ---- - -### hugegraph-hubble +## Quick start -**Purpose**: Web-based graph management and visualization platform +Start a HugeGraph Server first, then choose the tool that matches the task. -**Key Features**: -- Multi-graph workspace & connection management -- Interactive schema management with graphical editor -- Comprehensive data loading dashboard -- Dynamic graph visualization with path and topology canvas -- Built-in Gremlin query console & algorithm explorer -- Fine-grained user authentication & multi-language localization (i18n) +### Hubble -**Technology Stack**: Spring Boot + React + TypeScript + MobX + Ant Design - -**Entry Point**: `bin/start-hubble.sh` (default port: 8088) - -**Quick Start**: ```bash -cd hugegraph-hubble/apache-hugegraph-hubble-*/bin -./start-hubble.sh # Background mode -./start-hubble.sh -f # Foreground mode -./stop-hubble.sh # Stop server +docker run -d --name hubble -p 127.0.0.1:8088:8088 hugegraph/hubble ``` -📖 [Documentation](https://hugegraph.apache.org/docs/quickstart/hugegraph-hubble/) | 📁 [Source](./hugegraph-hubble) - ---- +This starts Hubble only. For current source builds, `server.direct_url` must name a Server address reachable from inside the container; container `127.0.0.1` is Hubble itself, not the host. Edit a copy of `hugegraph-hubble/hubble-dist/assembly/static/conf/hugegraph-hubble.properties` and mount it at `/hubble/conf/hugegraph-hubble.properties`, using `host.docker.internal` or a shared Docker network. See the [Hubble deployment section](hugegraph-hubble/README.md#3-user-docker-image-convenient-for-testdev) for published-image and source-build details. Review Comment: Fixed in 2316c4b: the mounted Hubble configuration now instructs users to set server.host=0.0.0.0 so the container can accept traffic from the published port. Docker was not run locally. ########## README.md: ########## @@ -1,511 +1,138 @@ -# hugegraph-toolchain +# Apache HugeGraph Toolchain [](https://www.apache.org/licenses/LICENSE-2.0.html) -[](https://github.com/apache/hugegraph-toolchain/actions/workflows/client-ci.yml) -[](https://github.com/apache/hugegraph-toolchain/actions/workflows/loader-ci.yml) -[](https://github.com/apache/hugegraph-toolchain/actions/workflows/hubble-ci.yml) -[](https://github.com/apache/hugegraph-toolchain/actions/workflows/tools-ci.yml) +[](https://github.com/apache/hugegraph-toolchain/actions/workflows/client-ci.yml) +[](https://github.com/apache/hugegraph-toolchain/actions/workflows/loader-ci.yml) +[](https://github.com/apache/hugegraph-toolchain/actions/workflows/hubble-ci.yml) +[](https://github.com/apache/hugegraph-toolchain/actions/workflows/tools-ci.yml) [](https://mvnrepository.com/artifact/org.apache.hugegraph/hugegraph-toolchain) -[](https://deepwiki.com/apache/hugegraph-toolchain) -## What is HugeGraph Toolchain? +HugeGraph Toolchain is the client and operations suite for [Apache HugeGraph](https://github.com/apache/hugegraph). It provides application SDKs, bulk data loading, browser-based graph management, command-line utilities and Spark integration. -A comprehensive suite of client SDKs, data tools, and management utilities for [Apache HugeGraph](https://github.com/apache/hugegraph) graph database. Build applications, load data, and manage graphs with production-ready tools. +**Start here:** [Choose a tool](#choose-a-tool) · [Quick start](#quick-start) · [Modules](#modules) · [Documentation](#documentation) · [Development](#development) -Hubble's primary authentication and connection design targets HugeGraph `1.8/master`: PD discovery supplies the server address, anonymous mode uses a real unauthenticated client, and account/GraphSpace permissions are reduced to four readable presets. A thin adapter keeps 1.7 usable and limits 1.5 to its standalone core graph workflow; version checks are centralized rather than spread across UI pages. +## Choose a tool -### Hubble Workbench +| Goal | Component | Entry point | +|---|---|---| +| Build a Java application | [`hugegraph-client`](hugegraph-client/) | `HugeClient` SDK | +| Import CSV, JSON, JDBC, HDFS or Kafka data | [`hugegraph-loader`](hugegraph-loader/) | `hugegraph-loader.sh` | +| Explore graphs and manage schemas in a browser | [`hugegraph-hubble`](hugegraph-hubble/) | Hubble Web UI | +| Back up, restore, migrate or inspect graphs | [`hugegraph-tools`](hugegraph-tools/) | `bin/hugegraph` | +| Read or write HugeGraph from Spark | [`hugegraph-spark-connector`](hugegraph-spark-connector/) | Spark DataSource | +| Use a Go client | [`hugegraph-client-go`](hugegraph-client-go/) | Go package | +| Use Python | [HugeGraph Python client](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-python-client) | `pyhugegraph` | -Hubble brings graph exploration, schema preparation, asynchronous analysis, and distributed cluster operations into one workspace. +The Java client is the shared foundation for Loader, the Hubble backend, Tools and the Spark connector. The Hubble frontend communicates with its backend. A client contract change therefore requires validation of the affected downstream modules. - - -### Distributed Operations - -The cluster overview keeps service topology, node health, source status, and capacity facts in one operational view. - - - -**Quick Navigation**: [Architecture](#architecture-overview) | [Quick Start](#quick-start) | [Modules](#module-overview) | [Build](#build--development) | [Docker](#docker) | [Related Projects](#related-projects) - -## Related Projects - -**HugeGraph Ecosystem**: -1. [hugegraph](https://github.com/apache/hugegraph) - Core graph database (**[pd](https://github.com/apache/hugegraph/tree/master/hugegraph-pd)** / **[store](https://github.com/apache/hugegraph/tree/master/hugegraph-store)** / **[server](https://github.com/apache/hugegraph/tree/master/hugegraph-server)** / **[commons](https://github.com/apache/hugegraph/tree/master/hugegraph-commons)**) -2. [hugegraph-computer](https://github.com/apache/hugegraph-computer) - Distributed graph computing system -3. [hugegraph-ai](https://github.com/apache/hugegraph-ai) - Graph AI/LLM/Knowledge Graph integration -4. [hugegraph-website](https://github.com/apache/hugegraph-doc) - Documentation and website - -## Architecture Overview - -```mermaid -graph TB - subgraph server ["HugeGraph Server"] - SERVER[("Graph Database")] - end - - subgraph distributed ["Distributed Mode (Optional)"] - PD["hugegraph-pd<br/>(Placement Driver)"] - STORE["hugegraph-store<br/>(Storage Nodes)"] - end - - subgraph clients ["Client SDKs"] - CLIENT["hugegraph-client<br/>(Java)"] - end - - subgraph data ["Data Tools"] - LOADER["hugegraph-loader<br/>(Batch Import)"] - SPARK["hugegraph-spark-connector<br/>(Spark I/O)"] - end - - subgraph mgmt ["Management Tools"] - HUBBLE["hugegraph-hubble<br/>(Web UI)"] - TOOLS["hugegraph-tools<br/>(CLI)"] - end - - SERVER <-->|REST API| CLIENT - PD -.->|coordinates| STORE - SERVER -.->|distributed backend| PD - - CLIENT --> LOADER - CLIENT --> HUBBLE - CLIENT --> TOOLS - CLIENT --> SPARK - HUBBLE -.->|PD discovery UI| PD - - LOADER -.->|Sources| SRC["CSV | JSON | HDFS<br/>MySQL | Kafka"] - SPARK -.->|I/O| SPK["Spark DataFrames"] - - style distributed stroke-dasharray: 5 5 -``` - -<details> -<summary>ASCII diagram (for terminals/editors)</summary> - -``` - ┌─────────────────────────┐ - │ HugeGraph Server │ - │ (Graph Database) │ - └───────────┬─────────────┘ - │ REST API - ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┼ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐ - Distributed (Optional)│ - │ ┌───────────┐ │ ┌───────────┐ │ - │hugegraph- │◄──────┴──────►│hugegraph- │ - │ │ pd │ │ store │ │ - └───────────┘ └───────────┘ - └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘ - │ - ┌─────────────────────┼─────────────────────┐ - │ │ │ - ▼ ▼ ▼ - ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ - │ hugegraph- │ │ Other Client │ │ Other REST │ - │ client (Java) │ │ SDKs (Go/Py) │ │ Clients │ - └───────┬────────┘ └────────────────┘ └────────────────┘ - │ depends on - ┌───────┼───────────┬───────────────────┐ - │ │ │ │ - ▼ ▼ ▼ ▼ -┌────────┐ ┌────────┐ ┌──────────┐ ┌───────────────────┐ -│ loader │ │ hubble │ │ tools │ │ spark-connector │ -│ (ETL) │ │ (Web) │ │ (CLI) │ │ (Spark I/O) │ -└────────┘ └────────┘ └──────────┘ └───────────────────┘ -``` -</details> - -## Quick Start - -### Prerequisites - -| Requirement | Version | Notes | -|-------------|---------|-------| -| JDK | 17+ | Build and run the core tools with Java 17 | -| Maven | 3.6.3+ | For building from source | -| HugeGraph Server | Current 1.8 or official 1.7.0 | See the migration guide for Server 1.5 scope | - -For the Java 17 candidate SDK, upgrade procedure and compatibility boundary, see [the migration guide](docs/java17-migration.md). - -### Choose Your Path - -| I want to... | Use This | Get Started | -|--------------|----------|-------------| -| Visualize graphs via Web UI | Hubble | Docker: `docker run -p 8088:8088 hugegraph/hugegraph-hubble` | -| Load CSV/JSON data into graph | Loader | CLI with JSON mapping config ([docs](https://hugegraph.apache.org/docs/quickstart/hugegraph-loader/)) | -| Build a Java app with HugeGraph | Client | Maven dependency ([example](#hugegraph-client)) | -| Backup/restore graphs | Tools | CLI commands ([docs](https://hugegraph.apache.org/docs/quickstart/hugegraph-tools/)) | -| Process graphs with Spark | Spark Connector | DataFrame API ([module](#hugegraph-spark-connector)) | - -### Docker Quick Start - -```bash -# Hubble Web UI (port 8088) -docker run -d -p 8088:8088 --name hubble hugegraph/hugegraph-hubble - -# Loader (batch data import) -docker run --rm hugegraph/hugegraph-loader ./bin/hugegraph-loader.sh -f example.json -``` - -## Module Overview - -Before committing a new source or test file, run the same license-header check -used by CI (`license-eye` from `apache/skywalking-eyes` is required): - -```bash -./tools/check-license-header.sh -``` - -Do not use shortened Apache headers: the complete header configured in -`.licenserc.yaml` is required. - -### hugegraph-client - -**Purpose**: Official Java SDK for HugeGraph Server - -**Key Features**: -- Schema management (PropertyKey, VertexLabel, EdgeLabel, IndexLabel) -- Graph operations (CRUD vertices/edges) -- Gremlin query execution -- Built-in traversers (shortest path, k-neighbor, k-out, paths, etc.) -- Multi-graph and authentication support - -**Entry Point**: `org.apache.hugegraph.driver.HugeClient` - -**Quick Example**: -```java -HugeClient client = HugeClient.builder("http://localhost:8080";, "hugegraph").build(); - -// Schema management -client.schema().propertyKey("name").asText().ifNotExist().create(); -client.schema().vertexLabel("person") - .properties("name") - .ifNotExist() - .create(); - -// Graph operations -Vertex vertex = client.graph().addVertex(T.label, "person", "name", "Alice"); -``` - -📖 [Documentation](https://hugegraph.apache.org/docs/quickstart/hugegraph-client/) | 📁 [Source](./hugegraph-client) - ---- - -### Other Client SDKs - -<details> -<summary><b>hugegraph-client-go</b> (Go SDK - WIP)</summary> - -**Purpose**: Official Go SDK for HugeGraph Server - -**Key Features**: -- RESTful API client for HugeGraph -- Schema and graph operations -- Gremlin query support -- Idiomatic Go interface - -**Entry Point**: `github.com/apache/hugegraph-toolchain/hugegraph-client-go` - -**Quick Example**: -```go -import "github.com/apache/hugegraph-toolchain/hugegraph-client-go" - -client := hugegraph.NewClient("http://localhost:8080";, "hugegraph") -// Schema and graph operations -``` - -📁 [Source](./hugegraph-client-go) - -</details> - -> **Looking for other languages?** See [hugegraph-python-client](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-python-client) in the hugegraph-ai repository. - ---- - -### hugegraph-loader - -**Purpose**: Batch data import tool from multiple data sources - -**Key Features**: -- **Sources**: CSV, JSON, HDFS, MySQL, Kafka, existing HugeGraph -- JSON-based mapping configuration -- Parallel loading with configurable threads -- Error handling and retry mechanisms -- Progress tracking and logging - -**Entry Point**: `bin/hugegraph-loader.sh` - -**Quick Example**: -```bash -# Load data from CSV -./bin/hugegraph-loader.sh -f mapping.json -g hugegraph - -# Example mapping.json structure -{ - "vertices": [ - { - "label": "person", - "input": { "type": "file", "path": "persons.csv" }, - "mapping": { "name": "name", "age": "age" } - } - ] -} +```text +HugeGraph Server + ▲ + │ REST APIs + │ +HugeGraph Java Client + ├─ Loader + ├─ Hubble backend ◀─ HTTP ── Hubble frontend + ├─ Tools + └─ Spark Connector ``` -📖 [Documentation](https://hugegraph.apache.org/docs/quickstart/hugegraph-loader/) | 📁 [Source](./hugegraph-loader) - ---- - -### hugegraph-hubble +## Quick start -**Purpose**: Web-based graph management and visualization platform +Start a HugeGraph Server first, then choose the tool that matches the task. -**Key Features**: -- Multi-graph workspace & connection management -- Interactive schema management with graphical editor -- Comprehensive data loading dashboard -- Dynamic graph visualization with path and topology canvas -- Built-in Gremlin query console & algorithm explorer -- Fine-grained user authentication & multi-language localization (i18n) +### Hubble -**Technology Stack**: Spring Boot + React + TypeScript + MobX + Ant Design - -**Entry Point**: `bin/start-hubble.sh` (default port: 8088) - -**Quick Start**: ```bash -cd hugegraph-hubble/apache-hugegraph-hubble-*/bin -./start-hubble.sh # Background mode -./start-hubble.sh -f # Foreground mode -./stop-hubble.sh # Stop server +docker run -d --name hubble -p 127.0.0.1:8088:8088 hugegraph/hubble ``` -📖 [Documentation](https://hugegraph.apache.org/docs/quickstart/hugegraph-hubble/) | 📁 [Source](./hugegraph-hubble) - ---- +This starts Hubble only. For current source builds, `server.direct_url` must name a Server address reachable from inside the container; container `127.0.0.1` is Hubble itself, not the host. Edit a copy of `hugegraph-hubble/hubble-dist/assembly/static/conf/hugegraph-hubble.properties` and mount it at `/hubble/conf/hugegraph-hubble.properties`, using `host.docker.internal` or a shared Docker network. See the [Hubble deployment section](hugegraph-hubble/README.md#3-user-docker-image-convenient-for-testdev) for published-image and source-build details. -### hugegraph-tools +Open `http://127.0.0.1:8088` after Hubble starts. -**Purpose**: Command-line utilities for graph operations +### Loader -**Key Features**: -- Backup and restore graphs -- Graph migration -- Graph cloning -- Metadata management -- Batch operations +First [download or build the Toolchain distribution](hugegraph-loader/README.md#2-quick-start). Change into the extracted `apache-hugegraph-toolchain-<version>/apache-hugegraph-loader-<version>` directory, replacing `<version>` with the distribution version. Run the launcher there so its sibling `lib` and `conf` directories are available: -**Entry Point**: `bin/hugegraph` CLI commands - -**Quick Example**: ```bash -# Backup graph -bin/hugegraph backup -t all -d ./backup - -# Restore graph -bin/hugegraph restore -t all -d ./backup +sh bin/hugegraph-loader.sh -f /path/to/mapping.json -g hugegraph ``` -📁 [Source](./hugegraph-tools) - ---- +The mapping file defines input sources, vertex and edge mappings, identifiers and error handling. See the [Loader guide](https://hugegraph.apache.org/docs/quickstart/hugegraph-loader/) for complete examples. -### hugegraph-spark-connector +### Java client -**Purpose**: Spark integration for reading and writing HugeGraph data +Use the released `org.apache.hugegraph:hugegraph-client` artifact listed in [Maven Central](https://mvnrepository.com/artifact/org.apache.hugegraph/hugegraph-client), and put the selected release version in the application POM. The [Client module](hugegraph-client/) owns coordinate, compatibility and API details. -**Key Features**: -- Read HugeGraph vertices/edges as Spark DataFrames -- Write DataFrames to HugeGraph -- Spark SQL support -- Distributed graph processing - -**Entry Point**: Scala API with Spark DataSource v2 - -**Quick Example**: -```scala -// Read vertices as DataFrame -val vertices = spark.read - .format("hugegraph") - .option("host", "localhost:8080") - .option("graph", "hugegraph") - .option("type", "vertex") - .load() +```java +import org.apache.hugegraph.driver.HugeClient; +import org.apache.hugegraph.structure.constant.T; -// Write DataFrame to HugeGraph -df.write - .format("hugegraph") - .option("host", "localhost:8080") - .option("graph", "hugegraph") - .save() +try (HugeClient client = HugeClient.builder("http://localhost:8080";, "hugegraph").build()) { + client.schema().propertyKey("name").asText().ifNotExist().create(); + client.schema().vertexLabel("person").properties("name").ifNotExist().create(); + client.graph().addVertex(T.LABEL, "person", "name", "Alice"); +} ``` -📁 [Source](./hugegraph-spark-connector) +Select a Client version compatible with the target Server rather than copying a repository development version into an application. -## Maven Dependencies +## Modules -```xml -<!-- Note: Use the latest release version in Maven Central --> -<dependency> - <groupId>org.apache.hugegraph</groupId> - <artifactId>hugegraph-client</artifactId> - <version>1.7.0</version> -</dependency> +| Module | Responsibility | +|---|---| +| `hugegraph-client` | Java schema, graph, Gremlin, traverser, authentication and administration APIs | +| `hugegraph-loader` | Parallel import pipeline for files, databases, messaging systems and existing graphs | +| `hugegraph-hubble` | Web UI for connections, schemas, loading, querying, visualization, analysis and cluster operations | +| `hugegraph-tools` | Backup, restore, migration, cloning and metadata commands | +| `hugegraph-spark-connector` | Spark DataFrame read and write integration | +| `hugegraph-client-go` | Go client under active development | +| `hugegraph-dist` | Aggregate packaging and distribution assembly | -<dependency> - <groupId>org.apache.hugegraph</groupId> - <artifactId>hugegraph-loader</artifactId> - <version>1.7.0</version> -</dependency> -``` +Module READMEs own detailed commands and configuration. The root README stays focused on choosing the correct component and reaching those documents. -Check [Maven Central](https://mvnrepository.com/artifact/org.apache.hugegraph) for the latest versions. +## Documentation -## Build & Development +- [Repository documentation index](docs/README.md): CI, Java migration, module ownership and documentation rules. +- [Official Toolchain guides](https://hugegraph.apache.org/docs/): user-facing Client, Loader, Hubble and Tools documentation. +- Module directories: closest source, examples and module-specific README files. +- [`AGENTS.md`](AGENTS.md): repository constraints, build/test selection and code-navigation guidance. +- [`.serena/README.md`](.serena/README.md): compact agent navigation cache linked back to authoritative files. -### Full Build +Every durable Markdown page should be reachable from this index or a module-local entry point. Avoid maintaining the same procedure in the root README, module README and agent notes. -Normal builds use the 1.8.0 SDK and release packaging checks. Select the staging repository in Maven settings and use an isolated local repository: +## Development -```bash -release_settings=/absolute/path/to/settings-with-selected-staging.xml -release_repository=$(mktemp -d /tmp/hugegraph-release-m2.XXXXXX) -mvn --settings "$release_settings" -Dmaven.repo.local="$release_repository" clean install \ - -DskipTests -Dmaven.javadoc.skip=true -ntp -``` +The main Java modules build with Java 17 and Maven. Read exact dependency and plugin versions from the POM files. -Distribution packaging requires Python 3.9 or newer. Release mode checks required SDK POM/JARs and packaged library versions and bytes, and rejects -candidate manifests. Add `-Papache-release` for the Apache release profile; see [release packaging](docs/java17-migration.md#release-packaging). -To build the pinned same-source 1.8.0 SDK instead, follow [the bootstrap instructions](docs/java17-migration.md#build-the-locked-candidate) and supply -`-Dmaven.repo.local="$candidate_dir/m2" -Dhugegraph.version=1.8.0 -Dsdk.validation.mode=candidate` to every module build. - -The aggregate Maven module is `org.apache.hugegraph:hugegraph-toolchain-dist:1.8.0`, distinct from Server's `hugegraph-dist` coordinate. -Its source directory remains `hugegraph-dist`; the release archive remains `apache-hugegraph-toolchain-1.8.0.tar.gz`. - -### Module-Specific Builds - -Until the 1.8.0 SDK is available in Maven Central, apply the same `--settings "$release_settings"` and -`-Dmaven.repo.local="$release_repository"` options from Full Build to each Maven command below. - -| Module | Build Command | -|--------|---------------| -| Client | `mvn -e compile -pl hugegraph-client -Dmaven.javadoc.skip=true -ntp` | -| Loader | `mvn install -pl hugegraph-client,hugegraph-loader -am -DskipTests -ntp` | -| Hubble | `mvn install -pl hugegraph-client,hugegraph-loader -am -DskipTests -ntp && cd hugegraph-hubble && mvn package -DskipTests -ntp` | -| Tools | `mvn install -pl hugegraph-client,hugegraph-tools -am -DskipTests -ntp` | -| Spark | `mvn install -pl hugegraph-client,hugegraph-spark-connector -am -DskipTests -ntp` | -| Go Client | `cd hugegraph-client-go && make all` | - -Hubble frontend builds require stable Node.js 24 (at least the version in -[`hubble-fe/.node-version`](hugegraph-hubble/hubble-fe/.node-version)) and the exact pnpm version -in [`hubble-fe/package.json`](hugegraph-hubble/hubble-fe/package.json). Install Corepack if your -Node distribution does not include it, then run `corepack enable` and `pnpm --version` from -`hugegraph-hubble/hubble-fe` before the Maven build. Later Node 24 patch/minor releases are supported; -Node 25 and prerelease builds require a separate compatibility upgrade. - -### Running Tests - -| Module | Test Type | Command | -|--------|-----------|---------| -| Client | Unit (no server) | `mvn test -pl hugegraph-client -Dtest=UnitTestSuite` | -| Client | API (server needed) | `mvn test -pl hugegraph-client -Dtest=ApiTestSuite` | -| Client | Functional | `mvn test -pl hugegraph-client -Dtest=FuncTestSuite` | -| Loader | Unit | `mvn test -pl hugegraph-loader -P unit` | -| Loader | File sources | `mvn test -pl hugegraph-loader -P file` | -| Loader | HDFS | `mvn test -pl hugegraph-loader -P hdfs` | -| Loader | JDBC | `mvn test -pl hugegraph-loader -P jdbc` | -| Loader | Kafka | `mvn test -pl hugegraph-loader -P kafka` | -| Hubble | Unit | `mvn test -P unit-test -pl hugegraph-hubble/hubble-be` | -| Tools | Functional | `mvn test -pl hugegraph-tools -Dtest=FuncTestSuite` | - -### Code Style - -Checkstyle is enforced via `tools/checkstyle.xml`: -- Max line length: 120 characters -- 4-space indentation (no tabs) -- No star imports -- No `System.out.println` - -Run checkstyle: ```bash -mvn checkstyle:check +mvn clean install -DskipTests -Dmaven.javadoc.skip=true -ntp +./tools/check-license-header.sh ``` -## Docker - -Official Docker images are available on Docker Hub: +Build only the affected module and its dependencies when possible: -| Image | Purpose | Port | -|-------|---------|------| -| `hugegraph/hugegraph-hubble` | Web UI | 8088 | -| `hugegraph/hugegraph-loader` | Data loader | - | - -**Examples**: ```bash -# Hubble -docker run -d -p 8088:8088 --name hubble hugegraph/hugegraph-hubble - -# Loader (mount config and data) -docker run --rm \ - -v /path/to/config:/config \ - -v /path/to/data:/data \ - hugegraph/hugegraph-loader \ - ./bin/hugegraph-loader.sh -f /config/mapping.json +mvn install -pl hugegraph-client -am -DskipTests -ntp +mvn install -pl hugegraph-loader -am -DskipTests -ntp +mvn install -pl hugegraph-hubble -am -DskipTests -ntp Review Comment: Fixed in 2316c4b: the example selects hugegraph-hubble/hubble-dist with -am. Maven validate selected the six-module reactor including Client, Loader, hubble-be and hubble-dist; a full build was not run. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
