Java API

The Java clientclient A language package that runs the relate engine inside a program's process: the Python, Node.js, Rust, Java, Go and Swift clients. Read more in the glossary is the artifact com.relate:relate, package com.relate, for Java 17 or later. It calls the relate C library, librelate_ffi, through JNA (Java Native Access), and its jar carries that library; the library's C application binary interface (C ABI) is version 2. Its two dependencies are JNA and Jackson databind. Every call is synchronous, and every failure is an unchecked exception. This page describes the client of relate 0.1.2.

Synopsis

package com.relate;

public class Database implements AutoCloseable {
    public static Database open(String uri);
    public static Database openReadOnly(String uri);
    public Connection connect();
    public synchronized Connection connect(String namespace);
    public synchronized void checkpoint();
    public synchronized void close();

    public static class Connection implements AutoCloseable {
        public Result query(String cypher);
        public synchronized Result query(String cypher, Map<String, ?> params);
        public synchronized void setNamespace(String namespace);
        public synchronized void begin();
        public synchronized String commit();
        public synchronized void rollback();
        public synchronized void close();
    }

    public static class Result {
        public List<String> columns();
        public List<List<Object>> rows();
        public QueryType getQueryType();
        public Namespace getNamespace();
        public String getBookmark();
        public List<Notification> getNotifications();
        public PlanDocument getPlan();
    }
}

Public types

Database

A failed open or openReadOnly throws DatabaseException with message internal error, code Neo.DatabaseError.General.UnknownError, GQLSTATUS 42000 and stage INTERNAL, whether the store is locked by another writer or missing. An unknown namespace throws ClientException: semantic error: DatabaseNotFound: Graph not found: <name>.

Connection

Database.Connection, a static nested class, has these methods:

Every method is synchronized: a connection serves one call at a time, and concurrent callers wait. A connection's own refusals, each a ClientException with code Neo.ClientError.Statement.SemanticError and GQLSTATUS 42000:

A failed commit() ends the transaction. A call on a closed connection or database throws RelateException with message connection is closed or database is closed and a null code.

Result

Database.Result, a static nested class, holds every row, copied out of the engine before query returns.

QueryType, Namespace, Severity and Category each have wire(), the string the C ABI carries: QueryType.READ_WRITE.wire() is "rw", Namespace.NEO4J.wire() is "neo4j", and a Severity or Category constant's string is its name. A Result carries no mutation counters, column types, or timings. A bookmark's <n> grows across every connection of the store and orders as a number: as strings, "relate:10" sorts before "relate:9".

Values

Each result cell is decoded into one Java type per Cypher kind:

An element idelement id The string elementId() returns for a node or relationship, such as 4:relate-neo4j:n0; it stays the same when the store is closed and opened again. Read more in the glossary is the string elementId() returns, such as 4:relate-neo4j:n0, so it round-trips through a parameter. The long ids are the deprecated numeric ids id() returns. A map key holding a NUL character, or a value kind the client does not know, throws RelateException instead of returning a value.

Parameters

query(cypher, params) binds each map entry as one Cypher value, with no JSON in between:

Any other type throws IllegalArgumentException before the statement runs, such as cannot bind parameter "x": unsupported Java type java.lang.Object. So do a vector coordinate of the wrong box type, as in cannot bind vector parameter with dtype INTEGER8: coordinate 0 is java.lang.Integer, expected Long, and a map key that is not a String, as in cannot bind nested map parameter "m": key 1 is java.lang.Integer, expected String. A value the engine refuses, such as an impossible date or an unknown zone, throws RelateException with stage INTERNAL. A statement that refers to a parameter the map lacks fails with semantic error: ParameterMissing: Expected parameter(s): <names>.

Errors

Every class has these getters:

A conflict surfaces on an auto-commit statement or on commit(). After an INTERNAL failure the handle may be poisoned; close() still works on it. A write on a read-only database throws ClientException with code Neo.ClientError.Statement.SemanticError and GQLSTATUS 42N18. The errors reference lists the engine's messages.

Notifications and plans

Notification has the getters getCode(), getGqlStatus(), getSeverity() (a Severity: INFORMATION or WARNING), getCategory() (a Category: PERFORMANCE, UNRECOGNIZED, DEPRECATION, SCHEMA or HINT), getTitle(), getDescription(), getRemedy() and getOperatorId(), a Long that is null on a statement-scoped notification. The list follows plan pre-order, then statement-scoped entries.

The plan classes have public fields:

Native library

The first use of Database in a JVM resolves the library once, in this order:

The system library path, java.library.path and jna.library.path are never searched. The platforms:

arm64 and x86_64 are accepted spellings of the same architectures. Any other platform throws RelateException beginning relate: unsupported platform os.name=. The plain jar carries all five libraries; each classifier jar carries one.

The extraction writes a temporary file and renames it into place, so concurrent JVMs never load a partial file. Old versions' directories stay until removed. A library of another C ABI version throws RelateException beginning incompatible librelate_ffi at <path>. Every jar also carries the skill file .agents/skills/relate/SKILL.md.

Limits

The limits come from the engine and are the same on every surface: a statement's text is at most 4194304 bytes (syntax error: query text of <n> bytes exceeds the maximum query size of 4194304 bytes), one value a statement builds is bounded by the expression memory cap, and a file-backed store has one writing open across every process. Limits and sizing lists each limit with its default and the setting that changes it.

Capabilities

Example

This program writes two Person nodes and a KNOWS relationship to an in-memory store and prints the Java type of each returned value:

import com.relate.Database;

public class Values {
    public static void main(String[] args) {
        try (Database db = Database.open(":memory:");
             Database.Connection conn = db.connect()) {
            var result = conn.query("""
                CREATE (ada:Person {name: 'Ada'})-[k:KNOWS {since: 2024}]->(grace:Person {name: 'Grace'})
                RETURN ada, k, 9007199254740993 AS big, 1.5 AS ratio, date('2024-05-06') AS day,
                       datetime('2024-05-06T09:30:00[Europe/Berlin]') AS meeting, duration('P1Y2M') AS term,
                       point({x: 1, y: 2}) AS spot, vector([1, 2, 3], 3, INT8) AS counts""");
            for (int i = 0; i < result.columns().size(); i++) {
                Object value = result.rows().get(0).get(i);
                System.out.println(result.columns().get(i) + ": " + value.getClass().getSimpleName() + " " + value);
            }
        }
    }
}

ada: Node Node[elementId=4:relate-neo4j:n0, id=0, labels=[Person], properties={name=Ada}]
k: Relationship Relationship[elementId=5:relate-neo4j:r0, id=0, startElementId=4:relate-neo4j:n0, startId=0, endElementId=4:relate-neo4j:n1, endId=1, type=KNOWS, properties={since=2024}]
big: Long 9007199254740993
ratio: Double 1.5
day: LocalDate 2024-05-06
meeting: ZonedDateTime 2024-05-06T09:30+02:00[Europe/Berlin]
term: DurationValue DurationValue[months=14, days=0, seconds=0, nanos=0]
spot: Point Point[srid=7203, x=1.0, y=2.0, z=null]
counts: VectorValue VectorValue[dtype=INTEGER8, coordinates=[1, 2, 3]]

See also

• Use the Java client: dependencies, open modes, parameters, transactions and errors, task by task.
• Embed relate in a Java app: the first program, step by step.
• API reference: every surface and the capability matrix.
• C ABI: the library this client calls.
• Errors: every engine message with its codes.
• Embedded graph in an app: the problem the clients solve.