Skip to main content
skill CX Codex

relate · relatedb, javascript — Claude Code skill: what it does, how to install

This Claude Code skill guides JavaScript and TypeScript work with Relate, a local graph database queried with openCypher. It covers connections, transactions, and result handling.

Apache-2.0 ★ 423 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add relatedb/relate --skill relate -a claude-code
Open on GitHub

What relate does

The skill explains how to use Relate from a Node.js application, from opening a database to running openCypher queries. Its guidance covers parameters, synchronous and asynchronous calls, transactions, result rows and summaries, graph extraction, and read-only access.

Install the application package with npm install @relate/relate. Relate runs inside the application process, with data stored in a local directory, an .rl file, or memory. Each database allows one writer process; concurrent readers can open it with { readOnly: true }.

What it helps with

  • open a local Relate database from JavaScript or TypeScript
  • bind parameters to an openCypher query
  • read query rows, counters, and summaries
  • extract graph entities from query results

Example prompts for the agent

  • Show how to open a local Relate database and run an openCypher query from TypeScript.
  • Explain a Relate transaction using begin(), commit(), and rollback().
  • Show how result.graph() returns nodes and relationships.

How to install relate

1Skills CLI (Vercel)

npx skills add relatedb/relate --skill relate -a claude-code

2Manually: put the files in place

~/.claude/skills/relate/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/relate/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about relate

How do I install relate in Claude Code?

Run npx skills add relatedb/relate --skill relate -a claude-code. The skill file is placed at ~/.claude/skills/relate/SKILL.md.

What does relate do?

It guides JavaScript and TypeScript development with the local Relate graph database, including openCypher queries, transactions, and result handling.

What does relate need to work?

The application code uses the Node.js package @relate/relate, installed with npm install @relate/relate. Its database engine runs in the application process.

Source text

SKILL.md · Apache-2.0
---
name: relate
description: Relate is an embedded openCypher graph database, and this is its Node.js/TypeScript package. Use this skill when writing JavaScript or TypeScript that creates, queries, or embeds a local graph database with Cypher — connecting, parameters, transactions, result handling (rows, counters, summaries, graph extraction), and read-only access.
---

# Relate (Node.js / TypeScript)

Relate embeds a full openCypher engine in-process (Rust core over the
typed C ABI v2; no server, no subprocess). `npm install
@relate/relate` — `require("@relate/relate")` /
`import { Database } from "@relate/relate"`. `query` is
synchronous (the engine runs in-process); `queryAsync` is the
Promise-returning form. Databases are a local directory, `":memory:"`, or
a `.rl` file. One writer process per database.

## Connect and query

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

const db = Database.open("./mydata");        // or ":memory:" / "./task.rl"
const conn = db.connect();                   // optional namespace: "system"...
const result = conn.query("CREATE (p:Person {name: $name})", { name: "Alice" });
const read = conn.query("MATCH (p:Person) RETURN p.name AS name");
for (const row of read.rows) console.log(row.name);
```

Parameters are `$name`, passed as a plain object lowered into the typed
params builder. Values: `null`, booleans, strings, numbers
(integer-valued binds INTEGER, otherwise FLOAT — `NaN`/`±Infinity` bind),
full-range `bigint`s, arrays, plain objects, and the typed classes
results decode to (`CypherDate`, `CypherTime`, `CypherLocalTime`,
`CypherDateTime`, `CypherLocalDateTime`, `CypherDuration`, `CypherPoint`,
`CypherVector`) — a decoded value binds back unchanged. `float(1)` binds
a FLOAT-typed 1.0. Transactions: `conn.begin()` / `conn.commit()` (it
returns the transaction's bookmark, `string | null`) /
`conn.rollback()`. Read-only access: `Database.open(path, { readOnly:
true })` — the store must exist; any number of readers, no writes or
checkpoints.

`conn.query` also doubles as a template tag — interpolated values become
auto-named `$p0, $p1, …` parameters (injection-safe by construction;
never concatenate values into statement text):

```js
const name = "Alice";
conn.query`MATCH (p:Person {name: ${name}}) RETURN p`;
```

Equal primitives dedup to one parameter (objects by identity); nested
arrays/plain objects are values; unsupported values (`undefined`,
functions, symbols, cyclic structures, non-plain objects — a JS `Date` is
ambiguous, construct a `CypherDateTime`) throw `TypeError` at any depth;
a shared (acyclic) reference binds at each place it appears.
No fragment composition — values are always data.

## Results

Rows are objects keyed by column name; `result.columns` is the RETURN
order. Every cell is the typed value walker's JS shape (ADR-0502 §1) —
there is no per-column type array; discriminate per value: `null`,
booleans, strings (interior NULs preserved), numbers (NaN/±Infinity as
themselves), int64 as `number` inside ±2^53-1 and `bigint` beyond
(`RETURN 9007199254740993` is exactly `9007199254740993n`), nodes
`{kind: "node", elementId, id, labels, properties}`, relationships
`{kind: "relationship", elementId, id, type, startElementId,
endElementId, startId, endId, properties}`, paths as alternating arrays,
`CypherPoint`, `CypherDate`,
`CypherTime`, `CypherLocalTime`, `CypherDateTime`, `CypherLocalDateTime`,
`CypherDuration` (four lossless components — `PT36H` ≠ `P1DT12H`),
`CypherVector`. `result.stats` carries the 11 mutation counters
(snake_case, zeros included). `result.queryType` is `"r"` / `"w"` /
`"rw"` / `"s"` and `result.namespace` the resolved namespace
(`"neo4j"`, `"system"`, `"system_ontologies"`). `result.bookmark` is the
auto-commit bookmark (`"relate:<n>"`) or null.
`result.notifications` is the engine-native query
notification list (ADR-0363) — always an array: `[]` on a plain run, the
plan-time list on `EXPLAIN` and `PROFILE` (`PROFILE` adds the
`EstimationMiss` kind). Each entry carries
`code`, `gql_status`, `severity`, `category`, `title`, `description`
(the diagnosis) and `remedy` (the action), plus `operator_id` on
operator-scoped kinds.

```js
const one = conn.query("MATCH (p:Person {name: $n}) RETURN p.name AS name", { n: "Alice" }).single();
const summary = conn.query("MATCH (p:Legacy) DELETE p").consume();
console.log(summary.counters.nodes_deleted, summary.queryType, summary.elapsedMs);
```

`single()` throws `ResultNotSingleError` on zero or more than one row.
`consume()` returns a `ResultSummary` — counters, resolved namespace,
query type, `elapsedMs` (engine-reported statement elapsed, ADR-0221:
parse, plan and run), its phase split `parseMs` / `planMs` / `executeMs`
(ADR-0491 — three disjoint windows whose sum never exceeds the total),
the `bookmark`, and the same `notifications` list.

## Errors

Every failure throws `RelateError` with the engine's own
classification: `code` (the Neo4j status code), `gqlStatus`, `stage`
(`"compile"` / `"runtime"` / `"internal"`), and `retryable` (also
`isRetriable`) — the retry decision. Retry only `retryable === true` (the
write-write conflict, the retryable workspace cap); never blind-retry.
`stage === "internal"` (a poisoned handle, a caught panic): close and
reopen instead of retrying.

```js
try {
  await conn.queryAsync("RETURN 1/0");
} catch (e) {
  console.log(e.code, e.retryable); // Neo.ClientError.Statement.ArithmeticError, false
}
```

`conn.queryAsync(cypher, params?)` (and the tag form) runs the call on
koffi's worker thread; the error rides the result handle back, so the
rejected promise is fully classified. Overlapping calls on one
connection are serialized; any sync call (`query`, `begin`, `commit`,
`rollback`, `setNamespace`) while an async query is in flight on the
same connection refuses.

## Graph extraction

`result.graph()` returns the unique graph entities the rows carry (nodes,
relationships, paths — nested values walked), de-duplicated by element
id, in first-seen order, as a `ResultGraph`:

```js
const g = conn.query("MATCH (a:Person)-[r:KNOWS]->(b:Person) RETURN a, r, b").graph();
g.nodes            // [{kind: "node", elementId, id, labels, properties}, ...]
g.relationships   // [{kind: "relationship", elementId, id, type, startElementId, endElementId, startId, endId, properties}, ...]
g.size             // entity count
```

Dependency-free conversion to Cytoscape.js or Sigma follows directly from
those shapes (`kind`, element ids, labels, type, endpoints, properties).

## Gotchas

- A result map key containing an interior NUL is refused with an error (the C ABI looks keys up NUL-terminated); string values keep their NULs.
- `":memory:"` vanishes when the process exits — use a path for durable work.
- One writer per database; open `{ readOnly: true }` for concurrent readers.
- Node and relationship values arrive as plain objects keyed by
  `elementId` (the engine's `elementId()` spelling, so
  `WHERE elementId(n) = $id` round-trips), `labels`/`properties` and
  `type`/`startElementId`/`endElementId`; every entity also carries the
  deprecated numeric ids (ADR-0506) — `id` is exactly Cypher `id()`, a
  relationship's `startId`/`endId` are `id(startNode(r))`/`id(endNode(r))`,
  all `number`-or-`bigint` by value — prefer `elementId` for identity;
  temporal values are component
  classes (`CypherDate` &c.), not ISO strings — render to text yourself.
- Int64 beyond ±2^53-1 is a `bigint` — pass big integers as `bigint`
  parameters, never through `Number` (LABS-901).
- Full TypeScript types ship in the package (`index.d.ts`).

Full spec: https://github.com/relatedb/relate — `docs/api/javascript/`.

© relatedb · Apache-2.0 · relatedb/relate

Similar skills

All skills for Data and databases →

relate by other authors comes first.

relate relatedb This Claude Code skill guides JVM projects through using Relate as a local graph database with Cypher. It activates when Java or Kotlin code needs to create, query, or embed the database. CX Codex +1 ★ 423repo stars relate relatedb This Claude Code skill guides Python work with Relate, an embedded openCypher graph database. It activates for building a local database, running Cypher queries, and handling query results. CX Codex +1 ★ 423repo stars amazon-neptune aws amazon-neptune is a Claude Code skill for Amazon Neptune Database and Neptune Analytics. It helps with graph queries, engine selection, Neo4j migration, and resource changes. CX Codex +1 2,200installs neo4j-driver-javascript-skill neo4j-contrib neo4j-driver-javascript-skill — a Claude Code skill for the official neo4j-driver v6. Activates when configuring connections, sessions, or transaction workflows for Neo4j in Node.js and browser apps. CX Codex +1 454installs typeorm Mindrally typeorm is a Claude Code skill for building with TypeORM in TypeScript and JavaScript. It comes into play when an agent edits entities, relations, or database queries. CX Codex +1 2,100installs neo4j-driver-go-skill neo4j-contrib The neo4j-driver-go-skill Claude Code skill guides Go code that connects to Neo4j with Driver v6. It activates for driver setup, query execution, session and transaction work, or debugging. CX Codex +1 815installs neo4j-cypher-guide tomasonjo neo4j-cypher-guide guides AI agents in writing current Neo4j Cypher read queries, choosing read subqueries, and traversing graphs with modern path patterns. CX Codex +1 1installs javascript-testing-patterns Seth Hobson The javascript-testing-patterns skill provides JavaScript and TypeScript testing examples, from unit tests to end-to-end flows. Use it when setting up test infrastructure or working with TDD. CX Codex +1 20,472installs

From the same set18

The whole set →
security-review The security-review Claude Code skill reviews code changes for security risks and suggests remediations. It activates for auth or permission changes, secrets and PII handling, public endpoints, and dependency upgrades. CX Codex +1 ★ 423repo stars neo4j-query-workload-skill The neo4j-query-workload-skill Claude Code skill builds a graph-database query workload one requirement at a time. It runs new queries against the dataset and checks earlier results for regressions. CX Codex +1 ★ 423repo stars relate This Claude Code skill guides JVM projects through using Relate as a local graph database with Cypher. It activates when Java or Kotlin code needs to create, query, or embed the database. CX Codex +1 ★ 423repo stars relate This Claude Code skill guides Python work with Relate, an embedded openCypher graph database. It activates for building a local database, running Cypher queries, and handling query results. CX Codex +1 ★ 423repo stars rust-reviewer The rust-reviewer skill for Claude Code and Codex reviews Rust code for ownership, lifetimes, and error handling issues. It examines the whole project, including unsafe blocks and idiomatic Rust patterns. CX Codex +1 ★ 423repo stars agent-backlog-autopilot The agent-backlog-autopilot Claude Code skill takes one agent-backlog task from selection through a pull request. It pauses after the draft checks pass and waits for a human to mark the PR ready for review. CX Codex +1 ★ 423repo stars stellar-code-quality-review The stellar-code-quality-review Claude Code skill audits maintainability, abstraction quality, and file growth. Its staged review examines changes and related code units. CX Codex +1 ★ 423repo stars stellar-structure stellar-structure — a subagent for Claude Code that runs a code structure pass covering size, decomposition, and layer placement. Triggered by the stellar-review pipeline. CX Codex +1 ★ 423repo stars

Project sponsors

Companies that keep this analytics open