Skip to main content
skill CX Codex

relate · relatedb, python — Claude Code skill: graph database tasks

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.

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 connecting to the embedded openCypher engine through the Python package relate. It explains query parameters and transactions, then shows ways to handle results: records can become dictionaries, DataFrames, or Arrow tables, and graph entities can be extracted for visualization.

Install the package with pip install relate-db. The to_arrow() method needs the arrow extra; to_df() needs pandas. A database can live in a local directory, an .rl file, or memory. Each database allows one writer process, and a connection must stay on the thread that opened it.

What it helps with

  • create a local graph database from Python
  • run a parameterized Cypher query
  • convert query results into a DataFrame or Arrow table
  • extract graph entities from query results for visualization

Example prompts for the agent

  • Write Python code to create a local Relate database and add nodes with Cypher.
  • Show how to pass parameters to a Cypher query using relate.
  • Convert a relate query result to a DataFrame and extract its graph for visualization.

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

What does the relate skill do?

It helps write Python code that connects to Relate’s local openCypher graph database and runs queries. It covers transactions and result formats, including DataFrames, Arrow tables, and graph extraction.

What is required to use relate?

Install the Python package with pip install relate-db. Arrow output requires the arrow extra, while DataFrame conversion requires pandas.

Source text

SKILL.md · Apache-2.0
---
name: relate
description: Relate is an embedded openCypher graph database, and this is its Python package (import relate). Use this skill when writing Python code that creates, queries, or embeds a local graph database with Cypher — connecting, parameters, transactions, result handling (records, DataFrames, Arrow, graph extraction), and visualization.
---

# Relate (Python)

Relate embeds a full openCypher engine in-process (Rust core, PyO3
extension; no server, no subprocess). `pip install relate-db` —
`import relate`. Databases are a local directory, `:memory:`, or a
`.rl` file. One writer process per database.

## Connect and query

```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 AS name"):
    print(row["name"], row.name)               # dict access and attribute access
db.close()
```

Parameters are `$name`, passed as a plain dict with string keys
(ADR-0219): `uuid.UUID` crosses as its canonical string,
`bytes`/`bytearray` as a list of byte values 0–255, tuples as lists, and
dicts are always maps — a `{"srid": …, "x": …, "y": …}` dict is NOT
silently turned into a point; pass `relate.Point(srid, x, y)` or use
`point($coords)` in Cypher. Non-dict params or non-string keys raise
`relate.ProgrammingError`, and so does a statement that references a
parameter missing from the dict (`ParameterMissing: Expected
parameter(s): <names>`) — pass `None` for null, never omit the key.
Transactions:
`db.autocommit = False`, then `db.commit()` / `db.rollback()` — closing
with an open transaction rolls back. `db.commit()` returns the
transaction's bookmark (`relate:<n>`, the engine's commit sequence,
increasing per store; `None` if nothing was written); an auto-commit
write's bookmark is `cursor.consume().bookmark`. Read-only access (multiple readers
per database, no writes or checkpoints):
`relate.connect(path, read_only=True)` — the store must exist.

## Result handling

Every row is a `Record` — a `dict` with read-only attribute access,
`.data()` (Neo4j-driver form: nodes/relationships become property dicts, paths
alternate node dicts and relationship types), `.to_dict()` (JSON-ready and
lossless: nodes keep `id`/`element_id`/`labels`/`properties`, relationships
add `type`/endpoint ids, paths are `{nodes, relationships}` — use this for
text2cypher output), and column-ordered `.keys()`. The cursor carries the Neo4j
driver's conveniences: `single()` (exactly one row or `ResultNotSingleError`),
`peek()`, `fetch(n)`, `data()`, `keys()`, and `consume()` — a
`ResultSummary` with the mutation counters, resolved namespace, query
type, `bookmark` (`relate:<n>` after an auto-commit write, else
`None`), `elapsed_ms` (engine-reported statement elapsed, ADR-0221) with its
`parse_ms`/`plan_ms`/`execute_ms` phase split (ADR-0491 — the PARSE /
PLAN / EXECUTE sub-windows of the total, answering where a slow statement
spends its time), and
`notifications` — the engine-native query-notification list (ADR-0363;
empty on a plain run, populated by `EXPLAIN`/`PROFILE`) — and `plan`, the
structured `relate.plan/v1` document (LABS-370, ADR-0381; `None` on a
plain run): the operator tree with per-node estimates, PROFILE metrics
(including the read-kind mix, the seek/walk phase times, the cumulative
`total_time_ms`, the arm's `loops`, the walk's start, `batched` —
whether the operator ran the batch scan/filter/project chain, and
`zone_skips` — how many conjunct-batch evaluations that chain's filter
provably replaced with the correct empty survivor set via the chunk's
derived per-column min/max zone) and the
operator's remedy-bearing warnings. Reach for `summary.plan` when a query is slow:
the `actual` numbers and the warnings name the operator to fix.
`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`.

```python
cur = db.execute("MATCH (p:Person) RETURN p.name AS name, p.age AS age")
cur.to_arrow()   # pyarrow.Table — pip install relate-db[arrow]
cur.to_df()      # pandas DataFrame — pip install relate-db[pandas]
```

`cur.graph()` returns the result's graph entities — every `Node`,
`Relationship`, `Path` in the rows (nested values walked), de-duplicated
by id — as a `ResultGraph` (`nodes`, `relationships`, id-ordered). Nodes
and relationships expose `id`, `labels`/`type`, `properties`,
`element_id` (exactly Cypher's `elementId()`: `4:rl-id:n0` /
`5:rl-id:r0`, so `WHERE elementId(n) = $id` finds it again),
`items()`, and `start`/`end`; relationships add `start_node_element_id` /
`end_node_element_id`. This is viz-independent:
convert to networkx/igraph without a bridge dependency (see
`references/networkx-igraph.md`), or render with the optional
`relate.viz.to_visualization_graph(cur)` (neo4j-viz).

## The native API

`relate.Database` is the thin native handle under `connect()` — use it
for `execute_arrow()` (Arrow IPC stream bytes), engine lifecycle
(`flush`, explicit transactions), or its `QueryResult` (dict rows
plus `namespace` / `query_type` / `bookmark` / `column_types` /
`notifications` / `plan`).
Everything ergonomic lives on the DB-API side; see
`references/native-api.md` for the comparison.

## Gotchas

- `:memory:` vanishes on close — use a path for durable work.
- One writer per database; multiple read-only processes are fine.
- Connections are thread-affine (`threadsafety` 1): use one only on the
  thread that opened it — any other thread gets a `ProgrammingError` (not
  fatal for the owning thread), and a foreign-thread drop is safe. In
  threaded servers, own the connection on one dedicated worker thread (or
  use `:memory:` per thread).
- Errors carry the engine's classification on every `relate.Error`:
  `e.neo4j_code`, `e.gql_status`, `e.stage` (`compile`/`runtime`/
  `internal`) and `e.retryable` — retry a transaction only when
  `e.retryable` is true (a write-write conflict). All four are `None` on a
  binding-level misuse (closed connection, wrong thread).
- Write counters live on `cursor.stats` (11 counters, zero-padded; Neo4j's
  counting: labels per node, every property write, schema DDL counted).
- Temporal values are `datetime` objects when stdlib carries them losslessly
  (microsecond-aligned, offset only); a value with sub-microsecond nanoseconds
  or an IANA zone name comes back as `relate.Temporal` — read `.text` (the
  engine's canonical ISO text, also `str()`), `.nanosecond`, `.zone_name`,
  `.offset_seconds`, or `.to_native()` for the lossy stdlib value. Nodes come
  back as rich `Node` objects, not dicts.
- Durations are always `relate.Duration` (`.months`, `.days`,
  `.seconds`, `.nanoseconds`; `str()` is the ISO text) — never a
  `timedelta`, so `PT36H != P1DT12H`. `.to_timedelta()` is the explicit
  lossy projection (raises `ValueError` on months or sub-µs). Bind
  `relate.Duration(months=1)` for a month duration.
- Vectors are `relate.Vector` (`.coordinate_type`, `.dimension`,
  `.values`) at every depth, never a dict; a returned one binds back as a
  parameter. Build new ones in Cypher: `vector($list, 3, FLOAT32)`.
- `bytes`/`bytearray` parameters arrive as a `LIST<INTEGER>` (0–255) and
  come back as a `list` of `int`; the engine's real byte array (ADR-0327)
  is Bolt-only and cannot be stored as a property.

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

© relatedb · Apache-2.0 · relatedb/relate

Similar skills

All skills for Programming languages →

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 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 svelte5-best-practices ejirocodes svelte5-best-practices — a skill that feeds your coding agent Svelte 5 runes, snippets and SvelteKit patterns while you write or refactor components. CX Codex +1 18,800installs solana-mobile solana-mobile Walks you through scaffolding, configuring and debugging Solana Mobile apps on Android: Expo templates, toolchain checks, emulators, a local validator. CX Codex +1 14,300installs msw-scripting MSW-Git msw-scripting guides authoring .mlua scripts for MapleStory Worlds, covering annotations, execution spaces, and playtesting. Useful when building MSW logic and debugging runtime issues. CX Codex +1 11,000installs seeker-connect solana-mobile seeker-connect wires a web, React Native or Kotlin dapp to the built-in wallet on a Seeker phone: Solana sign-in, message and transaction signing. CX Codex +1 9,700installs tauri-v2 nodnarbnitram Walks your agent through Rust commands, IPC and capabilities in Tauri v2, and heads off the build errors that usually eat an afternoon. CX Codex +1 8,500installs apollo-client apollographql apollo-client is a Claude Code skill for building React apps with Apollo Client 4.x. It activates for client setup, GraphQL queries and mutations, cache configuration, or troubleshooting. CX Codex +1 5,900installs

From the same set18

The whole set →
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 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 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 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

Project sponsors

Companies that keep this analytics open