Relate
Relate is an embedded, single-process openCypher graph database (openCypher
TCK coverage is measured by the project's spec harness, reporting-only) plus
a large slice of Neo4j's Cypher 25 / GQL-aligned extensions. One binary, no
server, no configuration. Databases are a local directory, a single .rl
file, or :memory:.
Selection guidance
Everything an agent normally needs — installation, CLI, Cypher, Python — is in this file. Reach for a focused reference only when the task calls for it:
| Need | Read |
|---|---|
Vector search: indexes, SEARCH, similarity functions |
vector |
| Geospatial: points, distance, bounding boxes, point indexes | spatial |
| Operations: storage forms, concurrency, ontology + schema discovery, import | operations |
| Safe operation: read-only use, limits, backups, destructive queries | agent-safety |
| Pull from Neo4j / Aura into a local database | pull |
| Push a local database (or a scoped subgraph) into Neo4j / Aura | push |
| Git history: coupling, ownership, churn, reviewers from a checkout | run-git-to-graph |
Command-kind extensions: author, install, or run relate run <name> packages |
client-extensions |
Agent-proposed feedback: draft the friction, get the person's approval, then relate agent-feedback |
client-cli |
Node.js client: @relate/relate install, native-lib resolution |
client-javascript |
| .NET client: C#, F#, VB, source build, native library and disposal | client-dotnet |
Java client: ai.relatedb:relate dependency, bundled natives, classifier jars |
client-java |
| Go client: cgo link, typed values, numeric + element ids, typed errors | client-go |
Browser/WASM client: @relate/relate-wasm init, OPFS, traps |
client-wasm |
iOS/macOS Swift client: SwiftPM Relate, XCFramework, concurrency traps |
client-swift |
Python client: relate-db errors, bookmarks, Duration/Vector, element ids |
client-python |
C ABI: librelate_ffi v2 build/link, walker, params builder, error channel |
client-c |
Installation
curl -sSfL https://relatedb.ai/install.sh | bash
relate --version # always verify the version before relying on behaviorOn Windows (PowerShell, cmd, or Git Bash — install.sh points there too):
powershell -ExecutionPolicy ByPass -c "irm https://relatedb.ai/install.ps1 | iex"It installs %LOCALAPPDATA%\Programs\relate\relate.exe and adds it to the
user PATH; open a new shell before running relate. relate upgrade
cannot replace a running .exe, so rerun the installer to upgrade
(relate upgrade --check still reports versions).
From source: git clone https://github.com/relatedb/relate && cargo build --release.
The Python package (relate-db) is pending its first tagged PyPI
publish; until then use make install-python from a source checkout.
CLI
relate query [STATEMENT] [--database PATH]
relate [OPTIONS] [--database PATH] [QUERY]Prefer the explicit form:
relate query "RETURN 2" --database ./mydataBefore writing Cypher from a natural-language request, read the ontology
first (opt in with RELATE_PREVIEW=ontology, ADR-0378) and take labels,
relationship types, and property names from it:
RELATE_PREVIEW=ontology relate query "CALL db.ontology.get()" --database ./mydatanull means no ontology is set. Without the opt-in the call fails with
preview feature 'ontology' is not enabled and SHOW PROCEDURES omits the
four db.ontology.* rows; if you cannot set it, fall back to schema
discovery and take labels, relationship types, and property names from
what the graph actually holds.
-d/--databasesets the store (directory,.rlbundle, or:memory:; default:memory:). The same flag is the store onquery, the path-first form,pull, andinfo.-dis the short form.STATEMENTor positionalQUERYruns one-shot (one statement or a;-separated list). With no statement and noqueryverb the process opens the interactive REPL on a terminal; piped or redirected, it prints help (ADR-0231).querywith noSTATEMENTis the interactive REPL on a terminal, or a script on stdin (relate query --database ./db < script.cypher).- Flags accept both
-jsonand--jsonforms. Key flags:--json/--csv/--markdown/--toon/--mode(--formatis an alias;--mode jsonlfor one JSON object per line;--mode envelopefor one{columns, columnTypes, rows, truncated}object per result set, which keeps the columns of an empty result and the engine-stamped per-column type names incolumnTypes, ADR-0224;--mode toonfor the compact TOON tabular form),--param N=V(repeatable),--snapshot-format json(empty dir only;parquet— whose checkpoints are ADR-0553's wide-column parts — too in builds with that codec, as--helplists),--logical-graph-size-limit SIZE,--concurrent-logical-workspace-limit SIZE(a positive value turns query admission on; omit leaves it off, ADR-0452),--max-rows N(rows printed per statement; under an agent harness the default is 100, with the cut named in-band in every machine mode — a terminal{"rowCap":{"kept":N,"total":M}}line in--jsonl,"rowCap"in--mode envelope— plus a stderr warning;--max-rows 0for all),-c/--command,--version. Piped or redirected stdout defaults totoonwhen agent mode is in effect (ADR-0407's ladder detects your harness; ADR-0426) and JSONL otherwise (ADR-0107);--mode jsonl(one object per line),--mode table,--json,--csv, or--markdownoverride it.--jsonprints one compact line when stdout is piped;--prettyindents it. - Read query notifications before rewriting a query:
EXPLAIN <statement>plans without executing and prints aNotifications:block after the plan table — one line per hint, each with the diagnosis and aRemedy:naming the action (give the patterns a join anchor, bound an expansion, create the named index, fix an unknown label/type/property spelling, replace a deprecated function).--mode envelope/--jsoncarry the same list as machine fields (code,gql_status,severity,category,title,description,remedy, plusoperator_idon operator-scoped entries). The plan table'sWarningscolumn and footer already cover the three plan-warning kinds, so do not expect them in the block. - Namespaces: every store has three fixed namespaces —
neo4j(user data, the default),system(SHOW/administration commands) andsystem_ontologies(visible only underRELATE_PREVIEW=ontology, ADR-0593: without it the connect fails "Graph not found: system_ontologies" andSHOW DATABASESlists the two CE rows; with it, every non-administration statement routed there fails with 42N17This database is not queryable. Use the db.ontology.* procedures on the user database 'neo4j' instead.— read the stored ontology throughCALL db.ontology.get()onneo4j, with the same opt-in set).--namespace NAME(case-insensitive) sets the session namespace for the whole run;USE <name>inside a statement switches it for that statement. Example:relate query --database ./db --namespace system -c 'SHOW DATABASES'. - REPL dot-commands:
.help .quit .exit .begin .commit .rollback .checkpoint .info .timer on|off..infoprints store metadata (persistent databases), exact live node/rel counts, and the index/constraint catalog — read-only, safe to run anytime. REPL editing is readline-style with in-session history; there is no tab completion or history file. The CLI prints no mutation summaries — verify writes with a query. - Commands (first argument only):
relate query …,relate skill install [--agent NAME]/relate skill remove/relate skill list/relate skill check(install state and drift detection),relate upgrade [--yes] [--check](aliasupdate).relate agent-context [COMMAND]prints the compact command/flag/exit-code briefing. --timeout DURATION(e.g.10s,500ms,2m) bounds each statement; a timed-out statement exits 7 (code: "timeout").--prettyforces indented JSON when piped.- Exit codes: 0 success, 1 runtime failure, 2 usage error, 5 conflict (write
conflict or store locked), 6 rejected statement (syntax/semantic/type
error), 7 query timeout (
--timeout). With--json/--jsonla failure also prints{"error":{"code","exit_code","kind","message","retryable"}}on stdout (a syntax error addscolumnandsource); branch oncode. When several statements stop on a failure the error addsstatement,statementsandcommitted(0inside an open.begin), so you know whether earlier statements already changed the store.relate <command> --helpprints one command's help. In pipe mode the first failing statement stops the batch.
Cypher
Reading:
MATCH (n:Person {name: 'Alice'}) RETURN n;
MATCH (a)-[:KNOWS*1..3]->(b) RETURN a, b; -- variable length
MATCH p = (a)-[:KNOWS]->(b) RETURN nodes(p), length(p); -- named path
OPTIONAL MATCH (p)-[:LIVES_IN]->(c) -- null on no matchWriting:
CREATE (a:Person {name: 'Alice', age: 30})
MERGE (p:Person {name: $name}) -- find-or-create
SET p.age = 31, p += {city: 'Berlin'} -- update / merge-props
REMOVE p.city -- drop a property
MATCH (n:Legacy) DETACH DELETE n -- delete + relsComposing: WITH (pipe, GROUP BY, ORDER BY, SKIP/LIMIT, WHERE),
UNWIND, UNION [ALL], FOREACH, LOAD CSV, CALL { ... } subqueries,
CALL (imports) { ... } scope clause, EXISTS/COUNT/COLLECT subquery
expressions, LET, FILTER, FINISH, NEXT statement chains.
Schema:
CREATE INDEX idx FOR (n:Person) ON (n.name);
CREATE VECTOR INDEX vidx FOR (n:Doc) ON (n.embedding) WITH [n.topic];
CREATE FULLTEXT INDEX ft FOR (n:Doc) ON EACH [n.title, n.body];
CREATE CONSTRAINT c FOR (p:Person) REQUIRE p.id IS UNIQUE;
SHOW INDEXES; SHOW CONSTRAINTS; SHOW FUNCTIONS;
CALL db.schema.nodeTypeProperties(); CALL db.schema.relTypeProperties();
CALL db.schema.visualization();
CALL db.ontology.get(); -- needs RELATE_PREVIEW=ontology
DROP INDEX idx;Extensions beyond openCypher: label expressions (n:A|B&!C), quantified
path patterns and selectors (SHORTEST 1, ANY, TRAIL), SEARCH
(vector + fulltext indexes), vector()/UUID types, string interpolation
(s'Hello {name}'), map comprehensions ({i IN list | k: v}), explicit
GROUP BY, the CYPHER 25 preamble (an accepted no-op — the only
supported Cypher version; every other integer fails, ADR-0584). Parameters
are $name (passed with --param or from Python dict keys). Every referenced
parameter must be supplied: a missing one fails the statement with
ParameterMissing: Expected parameter(s): <names>, never binds null.
Python
import relate
db = relate.connect("./mydata") # or ":memory:" / "./task.rl"
db.execute("CREATE (p:Person {name: $name})", {"name": "Alice"})
for row in db.execute("MATCH (p:Person) RETURN p.name"):
print(row["p.name"])
db.execute("BEGIN")
try:
db.execute("MATCH (n:Legacy) DELETE n")
db.execute("COMMIT")
except Exception:
db.execute("ROLLBACK")
db.close()Parameters (ADR-0219): uuid.UUID crosses as its canonical string;
bytes/bytearray as a list of byte values 0–255; tuples as lists; dicts
are always maps — a {"srid": …, "x": …, "y": …} dict is NOT turned into a
point, use relate.Point(srid, x, y) or point($coords); returned maps
keep key order. Non-dict params or non-string keys raise
relate.ProgrammingError.
Rows are driver-style Record dicts: row["p.name"], row.p_name-style
attribute access for valid identifiers, plus .data(), .keys(), and
.get(). The DB-API cursor also offers Neo4j-driver conveniences —
cursor.single() (exactly one row or ResultNotSingleError), peek(),
fetch(n), to_df() for a pandas DataFrame (optional
relate-db[pandas] extra), and to_arrow() for a pyarrow.Table
(optional relate-db[arrow] extra — .to_pandas() and
pl.from_arrow() both work). cursor.consume() returns a
ResultSummary (counters, resolved namespace, query type,
bookmark, engine-reported elapsed_ms). Errors carry the engine's
neo4j_code, gql_status, stage and retryable; durations arrive as
relate.Duration, vectors as relate.Vector, and element_id is
Cypher's elementId() — see client-python. cursor.description type codes come from
the engine-reported column types (ADR-0224): STRING/BINARY map to
themselves, INTEGER/FLOAT/BOOLEAN fold into NUMBER,
DATETIME/DATE/TIME fold into DATETIME, and graph, spatial, list,
map and duration columns — plus ANY (empty or Null first row) — report
None. cursor.graph() returns the result's
graph entities (nodes, relationships, paths — nested values walked),
de-duplicated by id, as a ResultGraph.
Native Database API adds execute_arrow() for zero-copy Arrow IPC into
Pandas/Polars. One writer process per database; ":memory:" is ephemeral.
For interactive graphs in Jupyter, the optional relate.viz helper
builds a neo4j-viz VisualizationGraph from a query result's graph
elements (nodes, relationships, paths) — render_widget() in Jupyter
(pip install neo4j-viz; see
docs/api/python/spec.md#visualization-relateviz-optional).
Agent rules (always follow)
- Run
relate --versionfirst and trust it over remembered behavior. - Use
:memory:only for disposable work — it vanishes on exit. - Prefer a new
.rldatabase per experimental task (relate -d ./task-<slug>.rl); copy an existing one instead of experimenting in place. - Load the ontology before generating Cypher from a natural-language
request —
CALL db.ontology.get()returns the stored ontology document as YAML (labels, relationship types, property names with types);nullmeans none is set. It requiresRELATE_PREVIEW=ontology; without it the call fails withpreview feature 'ontology' is not enabled. Steer labels, relationship types, and property names from the document. If it returnsnull, errors, or you cannot set the opt-in, fall back to schema discovery —SHOW INDEXES,SHOW CONSTRAINTS,CALL db.schema.nodeTypeProperties(),MATCH (n) UNWIND labels(n) AS l RETURN DISTINCT l(see operations). - Use
$parametersfor all values, never string-interpolated literals. - For machine parsing, remember piped or redirected stdout defaults to
toonwhen agent mode is in effect (ADR-0407's ladder — a harness like yours is likely detected; ADR-0426): onerows[N]{cols}:header plus one line per row.--mode jsonlgives one JSON object per line for line-based parsing,--json(-json) a JSON array, and--mode tablethe human-readable table. - Snapshot (
.checkpoint) before large destructive operations, and wrap them in.begin….commit/.rollbackso they are undoable. - Limit returned rows (
LIMIT, or aSKIP/LIMITwindow) — never dump a graph unbounded. - Retry only classified write conflicts; anything else fails loudly (see agent-safety).
- Never expose unauthenticated Bolt beyond loopback — bind the Bolt
surface (
relate serve --bolt PORT, ADR-0368) to127.0.0.1unless an authenticating proxy is in front of it.
Tips & gotchas
- Vector similarity scores are rebounded —
vector.similarity.cosinereturns a value in[0, 1](1.0 = identical direction, 0.5 = orthogonal); not the raw cosine. - One writer at a time — single-process engine; use the Bolt server for
multi-client access, or
relate serve --read-only[=snapshot|live]to serve a store beside the process writing it (ADR-0306). - A pipe hides failure —
relate query ... | headexits withhead's status, andtailcan cut the error itself. Prefer--max-rows,LIMITandSKIPover piping; if you must pipe,set -o pipefail, and judge success by the exit code or the JSONerrorenvelope, never the last lines. A capped result still exits0: readrowCap(or the stderr warning) before treating rows as complete. - Destructive DDL is silent —
DROP INDEX/DROP CONSTRAINTprint nothing on success; list first.