Skip to main content
skill CX Codex

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

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.

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 covers the Java library’s setup and use: adding a Maven or Gradle dependency, opening a database, issuing Cypher statements, and binding typed parameters. It also explains transactions, namespaces, result rows, query metadata, and read-only access.

Relate runs inside the application process and stores data in a local directory, an .rl file, or memory. Java 17 or newer is required. Only one writer process can use a database at a time, and a :memory: database disappears when the JVM exits. The skill also covers result types, query plans, and error handling.

What it helps with

  • add Relate to a Maven or Gradle project
  • open a local graph database and run Cypher statements
  • bind typed parameters and read query results
  • configure transactions or read-only database access

Example prompts for the agent

  • Show me how to open a Relate database and run a Cypher query from Java.
  • Add the Relate dependency with Gradle and bind parameters in this query.
  • Set up a transaction and read-only graph access in this Kotlin project.

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 installed at ~/.claude/skills/relate/SKILL.md.

What does relate do?

It guides JVM code through the Relate Java library for local graph storage and Cypher queries, including dependency setup, transactions, and reading results.

What does relate require?

The project needs Java 17 or newer and the Relate library added through Maven or Gradle. A database can have only one writer process at a time.

Source text

SKILL.md · Apache-2.0
---
name: relate
description: Relate is an embedded openCypher graph database, and this is its Java (JVM) library. Use this skill when writing Java, Kotlin or other JVM code that creates, queries, or embeds a local graph database with Cypher — adding the Maven/Gradle dependency, opening a database, running statements, binding typed parameters, transactions, namespaces, typed result rows and metadata, query notifications and plans, and read-only access.
---

# Relate (Java)

Relate embeds a full openCypher engine in-process (Rust core over the C
ABI, bound through JNA; no server, no subprocess). Every call is
synchronous. Databases are a local directory, `":memory:"`, or a `.rl`
file. One writer process per database. Java 17+.

## Dependency

The plain artifact bundles the native library for all five supported
platforms (darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-x64) —
no environment variable, no library path:

```xml
<dependency>
  <groupId>ai.relatedb</groupId>
  <artifactId>relate</artifactId>
  <version>${relate.version}</version>
</dependency>
```

For a smaller deployable, depend on one platform's classifier jar instead
(`osx-aarch_64`, `osx-x86_64`, `linux-aarch_64`, `linux-x86_64`,
`windows-x86_64` — the os-maven-plugin `${os.detected.classifier}` /
Gradle osdetector vocabulary). A classpath without the running platform's
native fails at first use with a `RelateException` naming the platform
and the classifier to add.

## Connect and query

```java
import ai.relatedb.Database;

try (Database db = Database.open("./mydata");      // or ":memory:" / "./task.rl"
     Database.Connection conn = db.connect()) {    // or db.connect("system")
    conn.query("CREATE (p:Person {name: 'Alice'})");
    Database.Result result = conn.query(
            "MATCH (p:Person) WHERE p.name = $name RETURN p.name AS name",
            java.util.Map.of("name", "Alice"));
    result.columns();   // List<String>: ["name"]
    result.rows();      // List<List<Object>>: [["Alice"]]
}
```

`query(cypher, params)` binds named parameters typed (one putter per Java
type — see Results below for the bindable types). Transactions:
`conn.begin()` / `conn.commit()` / `conn.rollback()`; `commit()` returns
the transaction's bookmark (`"relate:<n>"`, or null when the
transaction committed nothing). Read-only access:
`Database.openReadOnly(path)` — the store must exist; no writes or
checkpoints. `db.checkpoint()` folds the WAL into a checkpoint. `Database`
and `Connection` are `AutoCloseable` — close them (a file store cannot be
reopened in the same JVM otherwise).

## Results

Rows are positional lists in `columns()` order; cells hydrate typed through
the value walker (ABI v2, ADR-0502) — no JSON decode:

- Scalars: `Long` (every Cypher integer, the full int64 range), `Double`,
  `Boolean`, `String` (an interior `\u0000` survives), `null`.
- Graph entities: `Node` (elementId, id, labels, properties),
  `Relationship` (elementId, id, start/end element ids and their numeric
  start/end ids, type, properties), `Path` (alternating
  node, relationship, …, node) — records, not kind-tagged maps.

A map *key* holding an interior `\u0000` throws `RelateException` —
the C ABI's map lookup takes a NUL-terminated key, and the client refuses
the read rather than return the wrong key's value (string values keep
theirs).
- Temporals: `java.time` `LocalDate` / `LocalTime` / `OffsetTime` /
  `LocalDateTime` / `OffsetDateTime` / `ZonedDateTime` (zoned when the
  value keeps a zone, offset-only otherwise); durations as
  `DurationValue(months, days, seconds, nanos)`; points and vectors as
  `Point` / `VectorValue`.

`elementId` is the primary identity (`WHERE elementId(n) = $id`
round-trips); the `id` / `startId` / `endId` longs are the deprecated
legacy numeric ids (ADR-0506) — the values `id(n)` / `id(r)` /
`id(startNode(r))` / `id(endNode(r))` return.

The same types bind as parameters, plus `List` and `Map` (nested to any
depth); an unsupported Java type throws `IllegalArgumentException`.

- `getQueryType()` — `QueryType` enum `READ`, `WRITE`, `READ_WRITE` or `SCHEMA` (plan-time; `EXPLAIN`
  reports the wrapped statement's type without running it).
- `getNamespace()` — the resolved namespace: `Namespace` enum `NEO4J`, `SYSTEM` or
  `SYSTEM_ONTOLOGIES`.
- `getBookmark()` — `"relate:<n>"` after an auto-commit write, `null`
  when the statement committed nothing. Order bookmarks by the numeric
  `n`, not string order (`"relate:10"` sorts before `"relate:9"`).
- `getNotifications()` — typed `Notification`s (code, GQLSTATUS,
  `Severity`/`Category` enums, title, description, remedy, operator id); empty on a
  plain run, populated by `EXPLAIN` / `PROFILE`.
- `getPlan()` — the `relate.plan/v1` document for `EXPLAIN` /
  `PROFILE`, `null` on a plain run.

## Gotchas

- **Parameter binding is typed** — bind values with
  `query(cypher, Map.of(...))`; never concatenate untrusted input into the
  statement text.
- Errors throw typed exceptions: `TransientException` exactly when the
  engine marked the failure retryable (catch it to retry; a failed commit
  ends the transaction), `ClientException` for `Neo.ClientError.*`,
  `DatabaseException` for `Neo.DatabaseError.*`. Every one carries
  `getCode()`, `getGqlStatus()`, `getStage()` (the closed enum
  `RelateException.Stage`: `COMPILE` / `RUNTIME` / `INTERNAL`) and
  `isRetryable()` — classify on those, never on message text.
- `":memory:"` vanishes when the JVM exits — use a path for durable work.
- The bundled native is extracted once per version into the user cache
  (`~/Library/Caches/relate`, `$XDG_CACHE_HOME`/`~/.cache/relate`,
  `%LOCALAPPDATA%\relate`); relocate it with
  `-Drelate.native.cache=<dir>` (read-only home, `noexec` mounts).
- `RELATE_LIB` overrides the bundled native — a development escape
  hatch for a self-built library, not a deployment mechanism.
- JDK 24+ prints a JNI "restricted method" warning (JEP 472); silence it
  with `--enable-native-access=ALL-UNNAMED`.

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

© 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 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 relate relatedb 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. CX Codex +1 ★ 423repo stars spring-data-neo4j giuseppe-trisciuoglio spring-data-neo4j — a skill for integrating Neo4j graph database into Spring Boot applications. Teaches how to map nodes and relationships, write Cypher queries, configure repositories, and test with embedded databases. CX Codex +1 4,000installs 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 neo4j-cypher-skill neo4j-contrib neo4j-cypher-skill — a skill for writing, optimizing, and validating Cypher 25 queries against Neo4j 2025.x and 2026.x. Handles new queries, slow-query optimization, vector and fulltext search, subqueries, and batch operations. CX Codex +1 1,600installs neo4j-modeling-skill neo4j-contrib neo4j-modeling-skill — a skill for designing, reviewing, and refactoring Neo4j graph data models. CX Codex +1 1,200installs graph-database-expert martinholovsky graph-database-expert guides graph schema design, relationship modeling, and traversal query optimization with a focus on SurrealDB and Cypher. CX Codex +1 271installs graph-schema pproenca graph-schema is a Claude Code skill for designing, reviewing, and refactoring graph database schemas. It activates for node and relationship modeling or when mapping a domain into a graph. CX Codex +1 239installs

From the same set18

The whole set →
opencode-review-protocol The opencode-review-protocol Claude Code prompt defines a pull request review workflow. It posts line-specific findings, updates a summary comment, and writes a verdict for CI. CX Codex +1 ★ 423repo stars release-notes A prompt for Claude Code drafts relate release notes from the changelog and commit history. It runs for a tagged release. CX Codex +1 ★ 423repo stars 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 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 relate 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. 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

Project sponsors

Companies that keep this analytics open