HugeGraph Client Integration

HugeGraph Client Integration#

All external tools in the HugeGraph ecosystem — Loader, Hubble, and Tools — interact with HugeGraph exclusively through the hugegraph-client Java library over HTTP/HTTPS REST APIs. No tool has direct access to internal storage formats (RocksDB, HBase, etc.). The client library lives in hugegraph-toolchain/hugegraph-client and provides the shared API surface for all integrations.

HugeClient: The Core Entry Point#

HugeClient is the central facade. It is constructed via a fluent builder and exposes typed manager interfaces — each backed by a REST API domain:

Manager method	API domain
`schema()`	Property keys, vertex/edge labels, index labels
`graph()`	Vertex & edge CRUD, batch upsert
`gremlin()`	Gremlin query execution
`cypher()`	Cypher query execution
`traverser()`	Built-in traversal algorithms (shortest path, etc.)
`task()`	Async task lifecycle management
`auth()`	User/role/permission management
`graphs()`	Multi-graph management

Managers are initialized conditionally: graph-specific managers (SchemaManager, GraphManager, GremlinManager, TraverserManager) are only created when a graph name is supplied to the builder .

The builder is initialized as HugeClient.builder(url, graph) and supports chained config calls: configUser, configToken, configTimeout, configSSL, configPool, configHttpBuilder, and configGraphSpace. The default timeout is 20 s and the pool defaults to 4×CPU max connections .

Integration Patterns by Tool#

hugegraph-loader#

The standard loader creates a LoadContext which initializes HugeClient via HugeClientHolder.create(options). Connection parameters are declared in LoadOptions (--host, --port, --graph, --username, --password, --protocol, SSL truststore, connection pool sizes, --batch-size defaulting to 500, --retry-times defaulting to 3).

The insert pipeline: TaskManager dispatches BatchInsertTask instances asynchronously. Each task calls client.graph().addVertices() or client.graph().addEdges(). For upsert workloads, BatchVertexRequest / BatchEdgeRequest builders add update strategies. On batch failure, the task can fall back to single-row inserts .

ElementBuilder (and its concrete VertexBuilder/EdgeBuilder subclasses) handles field mapping, type conversion, null-key filtering, and ID strategy resolution before elements are passed to the client. The ID strategies supported are CUSTOMIZE_STRING, CUSTOMIZE_NUMBER, CUSTOMIZE_UUID, and PRIMARY_KEY .

Spark variant: HugeGraphSparkLoader runs the same ElementBuilder → GraphManager.addVertices/addEdges pipeline inside Spark foreachPartition. A second code path (sinkType=false) bypasses the REST API entirely and bulk-loads HFiles directly into HBase via HBaseDirectLoader — the only tool mode that does not go through the client library.

hugegraph-hubble#

Hubble connects via HugeClientUtil.tryConnect(), which builds a HugeClient from a GraphConnection entity (stores host, port, graph, protocol, credentials, SSL settings in the local DB) and validates the connection with a g.V().limit(1) Gremlin probe.

HugeClientPoolService (extends ConcurrentHashMap<Integer, HugeClient>) maintains a live pool keyed by connection ID. Service classes call poolService.getOrCreate(connId) — lazy-initializing on first access — and delegate to the appropriate manager:

Schema CRUD → client.schema() — SchemaService
Gremlin / async execution → client.gremlin() — GremlinQueryService
OLTP algorithms (shortest path, etc.) → client.traverser() — OltpAlgoService
Async task monitoring → client.task()

Hubble also exposes its own REST API Response wrapper ({status, data, message, cause}) to its frontend — distinct from the HugeGraph server's API responses.

hugegraph-tools#

ToolClient is a thin wrapper around HugeClient, constructed from a ConnectionInfo POJO. It re-exposes traverser(), graph(), schema(), graphs(), tasks(), gremlin(), and authManager() directly. HTTPS connections fall back to a default truststore at conf/hugegraph.truststore if none is provided . All backup/restore, graph clone, and auth management commands in hugegraph-tools go through this single wrapper.

Key Invariants#

All API interactions are over HTTP/HTTPS. The hugegraph-client library serializes graph structures (vertices, edges, schema) to JSON; the server deserializes and writes to the backend store. Tools never touch binary storage formats directly.
Authentication supports both username/password and token modes via HugeClientBuilder.
SSL is supported across all three tools; each requires a truststore file and password when using https://.
Connection pool defaults (4×CPU max connections, 2×CPU per route) are shared defaults in HugeClientBuilder and can be overridden in LoadOptions for loader-specific tuning .