Skip to Content
API ReferenceJava APIJava API Overview

Java API Reference

The NeuG Java API provides a Java-native driver for connecting to NeuG servers, executing Cypher queries, and consuming typed query results.

Overview

The Java driver is designed for application integration and service-side usage:

  • Create drivers to connect to a NeuG server over HTTP
  • Open sessions to execute Cypher queries
  • Read results through a typed ResultSet API
  • Inspect metadata using native NeuG Types

Deployment Model

The current Java SDK supports remote access over HTTP only, i.e., service mode.

  • Supported: connect to a running NeuG server with GraphDatabase.driver("http://host:port")
  • Not supported: embedded/in-process database access from Java

If you need embedded access, use the C++ or Python APIs. The Java SDK should be treated as a client for an already running NeuG service.

Usage

Add dependency in another Maven project

<dependency>
	<groupId>com.alibaba.neug</groupId>
	<artifactId>neug-java-driver</artifactId>
	<version>${neug.version}</version>
</dependency>

Core Interfaces

  • Driver - manages connectivity and creates sessions
  • Config - customizes connection and timeout behavior
  • Session - executes statements against a NeuG server
  • Transaction - groups multiple statements into one explicit transaction
  • ResultSet - reads rows and typed values from query results
  • ResultSetMetaData - inspects result column names, nullability, and native NeuG types

Quick Start

import com.alibaba.neug.driver.Driver;
import com.alibaba.neug.driver.GraphDatabase;
import com.alibaba.neug.driver.ResultSet;
import com.alibaba.neug.driver.Session;
 
public class Example {
	public static void main(String[] args) {
		try (Driver driver = GraphDatabase.driver("http://localhost:10000")) {
			driver.verifyConnectivity();
 
			try (Session session = driver.session()) {
				try (ResultSet rs = session.run("RETURN 1 AS value")) {
					while (rs.next()) {
						System.out.println(rs.getInt("value"));
					}
				}
			}
		}
	}
}

Start a NeuG Server

Before using the Java SDK, start a NeuG HTTP server that exposes the query endpoint. You can use either the C++ binary or the Python API to start the server.

Option A: Start with Python

If you have the neug Python package installed, you can start the server directly from Python:

from neug import Database
 
db = Database("/path/to/graph", mode="rw")
# Blocks until the process is killed (Ctrl+C or SIGTERM)
db.serve(port=10000, host="0.0.0.0", blocking=True, thread_num=0)

To run non-blocking (e.g. inside a larger script):

import time
from neug import Database
 
db = Database("/path/to/graph", mode="rw")
uri = db.serve(port=10000, host="0.0.0.0", blocking=False, thread_num=0)
print("Server started at:", uri)
 
try:
    while True:
        time.sleep(60)
except KeyboardInterrupt:
    db.stop_serving()

thread_num sets the service thread count. The default 0 auto-selects from the database max_thread_num. If set explicitly, it must be less than or equal to the database max_thread_num. With the default database thread setting, max_thread_num is resolved from hardware concurrency and falls back to 1 if the runtime cannot detect it. Service threads run TP queries concurrently, but each query uses one execution context and one thread.

Option B: Start with the C++ binary

1. Build the server binary

From the repository root:

cmake -S . -B build -DBUILD_EXECUTABLES=ON -DBUILD_HTTP_SERVER=ON
# macOS
cmake --build build --target rt_server -j$(sysctl -n hw.ncpu)
# Linux
cmake --build build --target rt_server -j$(nproc)

2. Start the server

./build/bin/rt_server --data-path /path/to/graph --http-port 10000 --host 0.0.0.0 --thread-num 0

Common options:

  • --data-path: path to the NeuG data directory
  • --http-port: HTTP port for Java clients, default is 10000
  • --host: bind address, default is 127.0.0.1
  • --thread-num: database max_thread_num and service thread_num. The default is 0: NeuG first resolves the database thread count, then resolves service threads from the resulting database max_thread_num. With the default database thread setting, the database thread count is resolved from hardware concurrency and falls back to 1 if the runtime cannot detect it. Service threads run TP queries concurrently, but each query uses one execution context and one thread.

Note: Make sure all local connections are closed before calling db.serve(). Once the server is running, no new local connections are allowed until db.stop_serving() is called.

Connect from Java

After the server is started via either option:

Driver driver = GraphDatabase.driver("http://localhost:10000");

Parameterized Queries

import java.util.HashMap;
import java.util.Map;
 
Map<String, Object> parameters = new HashMap<>();
parameters.put("name", "Alice");
parameters.put("age", 30);
 
try (Session session = driver.session()) {
	String query = "CREATE (p:Person {name: $name, age: $age}) RETURN p";
	try (ResultSet rs = session.run(query, parameters)) {
		if (rs.next()) {
			System.out.println(rs.getObject("p"));
		}
	}
}

Dependencies

The Java driver depends on the following libraries:

  • OkHttp - HTTP client
  • Protocol Buffers - response serialization
  • Jackson - JSON processing
  • SLF4J - logging facade

These dependencies are managed automatically by Maven.

API Documentation

The generated Javadoc can be built locally. See Build Javadoc Locally below.

Build Javadoc Locally

cd tools/java_driver
mvn -DskipTests javadoc:javadoc

The generated Javadoc is written to tools/java_driver/target/site/apidocs.

Last updated on
NeugDBServiceDriver