Three ways to run Relate, the embedded Cypher database

Relate is an open-source embedded graph database that speaks Cypher. It runs inside your own process, so there is no server to deploy and no signup. This guide shows three ways to run it, from the command line, embedded in an application, and driven by an agent.

The examples use the same two Cypher statements. The first creates a small graph with one person and one project:

CREATE (:Person {name: 'Ada'})-[:WORKS_ON {since: 2024}]->(:Project {name: 'relate'})

The second reads it back:

MATCH (p:Person)-[w:WORKS_ON]->(proj:Project)
RETURN p.name AS person, proj.name AS project, w.since AS since

Run it from the command line

Use the command line when you want to try Cypher or run a script. Install the relate binary:

curl -sSfL https://relatedb.ai/install.sh | bash

Open the interactive shell. With no --database option it starts on an in-memory database, and statements end with a semicolon:

relate query

Type the statement that creates the first nodes and the relationship between them, ending with ;:

CREATE (:Person {name: 'Ada'})-[:WORKS_ON {since: 2024}]->(:Project {name: 'relate'});

A CREATE with no RETURN returns no rows, so Relate reports what it wrote instead. Now read the graph back:

MATCH (p:Person)-[w:WORKS_ON]->(proj:Project)
RETURN p.name AS person, proj.name AS project, w.since AS since;

The shell prints one row:

+--------+----------+-------+
| person | project  | since |
+--------+----------+-------+
| "Ada"  | "relate" | 2024  |
+--------+----------+-------+

An in-memory database forgets everything when the shell closes. To keep the graph, name a file ending in .rl with --database. Relate creates it when it doesn't exist:

relate query --database ./team.rl

You can also run a statement once and exit, which suits scripts. This one reads the file back without being able to change it:

relate --database ./team.rl --read-only "MATCH (p:Person)-[w:WORKS_ON]->(proj:Project) RETURN p.name AS person, proj.name AS project, w.since AS since"

To bind a value instead of writing it into the statement, name it $name and pass it with --param:

relate --database ./team.rl --read-only --param name=Ada 'MATCH (:Person {name: $name})-[:WORKS_ON]->(proj:Project) RETURN proj.name AS project'

Embed it in an application

Use Relate embedded when the database belongs to your application, for example to hold an agent's memory, to load data for analysis, or to build test fixtures. The engine runs inside your process, so there is no connection string, no network and nothing to keep running beside the application.

Relate has clients for Rust, Python, Node.js, Java, Go and Swift. In a Node.js application, it looks a bit like this. The package carries the engine, so you don't need the command line tool:

npm install @relate/relate

Open a database, connect to it and call query. It returns the result directly, so there is nothing to await:

const { Database } = require("@relate/relate");
 
const conn = Database.open(":memory:").connect();
 
conn.query(
  "CREATE (:Person {name: 'Ada'})-[:WORKS_ON {since: 2024}]->(:Project {name: 'relate'})"
);
 
const result = conn.query(
  `MATCH (p:Person)-[w:WORKS_ON]->(proj:Project)
   RETURN p.name AS person, proj.name AS project, w.since AS since`
);
 
console.log(result.rows);
// [ { person: 'Ada', project: 'relate', since: 2024 } ]

A path ending in .rl opens a single-file database instead, and creates it when it doesn't exist:

const conn = Database.open("./team.rl").connect();

To bind a value, name it $name in the statement and pass an object as the second argument. The value never becomes part of the Cypher:

const { rows } = conn.query(
  "MATCH (:Person {name: $name})-[:WORKS_ON]->(proj:Project) RETURN proj.name AS project",
  { name: "Ada" }
);

The same engine compiles to WebAssembly, so a web page can embed it too. In the browser, creating the database looks like this:

import init, { RelateDb } from "@relate/relate-wasm";
 
await init();
const db = new RelateDb();

That's the whole of it, apart from serving the .wasm file and running the engine in a worker. How to run a Cypher engine in the browser with WebAssembly covers both, and Why we use Relate to provision databases for our learners explains how GraphAcademy uses it for Neo4j Fundamentals. The Relate browser guide has the full walkthrough.

Run it in an agent

Use Relate with an agent when you want it to keep its own data and answer questions about it. Relate has an agent skill that teaches an AI assistant to drive the database, so the agent writes the Cypher and you don't have to. Give your coding agent this prompt:

Set up relate for me. Read https://relatedb.ai/skill.md, install the relate agent skill, create a database, add my data, and answer my questions by writing Cypher queries.

The agent uses the relate command line tool from the first section. For output that is easy for an agent to read, Relate prints JSON when you pass -json, and the Relate guide to driving it from an agent covers error handling, exit codes and row limits.

Try it yourself

Neo4j Fundamentals runs its Cypher lessons in the browser on Relate, so you can write queries without installing anything.

Get Started with Relate

Install Relate, the embedded Cypher database. Seed a graph from a script and a CSV file, write data by hand and with an agent, then read it back.

View course