Node.js API

The relate Node.js 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 @relate/relate package: it loads the engine as a native library (librelate_ffi, the C ABI version 2) and runs it in the calling process against a storestore A relate database: a directory, a single .rl file, or :memory:, opened with --database. Read more in the glossary. query() is synchronous and queryAsync() returns a Promise of the same result. The package ships TypeScript types in index.d.ts; the signatures on this page are read from those types and the package source, and checked against @relate/relate 0.1.2 on Node.js 26; the package requires Node.js 18 or later.

Synopsis

const { Database } = require("@relate/relate");

const db = Database.open(uri, { readOnly: false });   // a Database
const conn = db.connect(namespace);                   // a Connection; namespace defaults to "neo4j"
const result = conn.query(cypher, params);            // a Result holding every row
const later = await conn.queryAsync(cypher, params);  // a Promise of a Result
conn.begin();
const bookmark = conn.commit();                       // "relate:<n>", or null
db.checkpoint();

Exports

The types file also exports the TypeScript types QueryType, Namespace, Int64, NodeValue, RelationshipValue, PathValue, Row, Stats, Notification, PlanDocument, PlanNode, PlanStartReason, PlanActual and ParamValue.

Loading

require("@relate/relate") finds the library in this order: the path in RELATE_LIB; the platform package @relate/<platform>-<arch> that npm installs as an optional dependency (darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-x64); then a source checkout's build directories. It then checks the library's ABI version.

Database

There is no close method. Each statement is durable when query() returns; the store stays open until the process exits.

Open options

A file-backed store has one writing open at a time. A directory store also opens readOnly: true beside its writer; a .rl store does not. A failed open throws a RelateError whose message is internal error, with stage "internal", gqlStatus 42000 and code Neo.DatabaseError.General.UnknownError; the message does not say whether the store was locked or missing.

Connection

While a queryAsync() is in flight, query, begin, commit, rollback and setNamespace on the same connection throw RelateError: a synchronous <call> cannot start while an async query is in flight on this connection, with code, gqlStatus and stage null. A synchronous call in the same tick as queryAsync() runs first, because the async statement starts on the next microtask.

Result

A Result holds every row from the moment query() returns.

Value mapping

Each result value carries its own type; there is no per-column type list.

A nodenode An entity in the graph: it carries zero or more labels and a map of properties, and relationships connect it to other nodes. Read more in the glossary and a relationshiprelationship A directed, typed connection between two nodes, with properties of its own; every relationship has exactly one type and a start and an end node. Read more in the glossary carry elementId, the string Cypher's elementId() returns (4:relate-neo4j:n0, 5:relate-neo4j:r0), and id, what id() returns. A pathpath An alternating sequence of nodes and relationships that a pattern matched, bound with p = … and read with nodes(p), relationships(p) and length(p). Read more in the glossary is an array of both. Byte arrays arrive as a list of integers 0 to 255, and UUIDs as strings.

undefined, functions, symbols, Date, Map, Set and other class instances throw a TypeError before the statement runs. Each TypeError the client throws has one of these messages; <path> is the parameter name in quotes, followed by [<i>] or .<key> for a nested value, such as "x"[0]:

Every integer field (the temporal and duration components, the values of an INTEGER* vector) follows the Int64 rule: a number, or a bigint beyond the safe range. Point coordinates, CypherFloat.value and the values of a FLOAT* vector are number.

Errors

retryable is true only when re-running the same work can succeed, such as after a write-write conflict, which can surface on a statement or on commit(). A stage of "internal" marks a failure outside the statement. The errors reference lists every engine message with its codes.

Limits

Capabilities

Example

An integer beyond Number.MAX_SAFE_INTEGER arrives as a bigint, and float() keeps a whole number a FLOAT:

const { Database, float } = require("@relate/relate");

const conn = Database.open(":memory:", { readOnly: true }).connect();
const row = conn.query(
  "RETURN 2024 AS since, 9007199254740993 AS big, toString($weight) AS weight, toString($count) AS count",
  { weight: float(1), count: 1 }
).single();
console.log(typeof row.since, row.since);
console.log(typeof row.big, row.big.toString());
console.log(row.weight, row.count);

number 2024
bigint 9007199254740993
1.0 1

A path from the team graph arrives as an array of node and relationship objects:

const { Database } = require("@relate/relate");

const TEAM = `
CREATE (ada:Person {name: 'Ada', role: 'engineer'}),
       (grace:Person {name: 'Grace', role: 'engineer'}),
       (noor:Person {name: 'Noor', role: 'maintainer'}),
       (relate:Project {name: 'relate', language: 'Rust'}),
       (tck:Project {name: 'opencypher-tck', language: 'Gherkin'}),
       (ada)-[:WORKS_ON {since: 2024}]->(relate),
       (grace)-[:WORKS_ON {since: 2023}]->(relate),
       (grace)-[:WORKS_ON {since: 2022}]->(tck),
       (noor)-[:MAINTAINS]->(relate),
       (ada)-[:KNOWS]->(grace)
`;

const conn = Database.open(":memory:").connect();
conn.query(TEAM);
const [ada, knows, grace] = conn.query("MATCH p = (:Person {name: 'Ada'})-[:KNOWS]->(:Person) RETURN p").single().p;
console.log(ada.kind, ada.properties.name, ada.elementId, ada.labels.join(","));
console.log(knows.kind, knows.type, knows.elementId, knows.startElementId, knows.endElementId);
console.log(grace.kind, grace.properties.name);

node Ada 4:relate-neo4j:n0 Person
relationship KNOWS 5:relate-neo4j:r4 4:relate-neo4j:n0 4:relate-neo4j:n1
node Grace

See also

• Use the Node.js client: open modes, typed values, templates, transactions, async queries, and errors in working programs.
• Embed relate in a Node.js app: the first program.
• Errors: every engine error with its codes.
• Python API: the same engine from Python.
• Embedded graph in an app: the problem the clients solve.